API First Principles & Guide for building award winning developer platform and products
APIs are taking over the world, some even say that APIs are the “digital assets” as companies have been monetizing their Platform APIs. Therefore it is critical to think harder before designing APIs that a lot of developers will rely on and use to build their custom applications.
In this article we will cover some of the key principles that many organizations including RingCentral has taken to heart in order to build award winning APIs — “Best in Communications API” as recognized by API World.
API First is a mindset that essentially means “Design Driven Development” where you treat APIs as first-class citizens for both internal and external developers. This way you define your “must-have” APIs from the ground up, instead of building a product and exposing the APIs later on.
10 Steps for API First Approach
1. API Communication & Planning: It all starts with a plan. The popular way to go about is by creating an API Governance Team that would include key stakeholders such as Software Architects & Engineers, and Product Managers all of whom would respectively advocate for technical and business requirements and check off on API Design before implementation begins.
Identify Business & Technical Needs
- What value/information does the API produce to developers? It is based on what information developers need that can be gotten from doing developer research.
- Start with listing your requirement in plain language and invite non-technical users to discuss the same, for example, “Our users have been asking to search books easily from our store, thus we need to design an API for the same”. Afterward, translate the English language use cases into technical use cases.
2. API Design using OpenAPI standard: It is essential to ensure that all APIs share the same format across platforms/products. Consider following OpenAPI standards when designing your APIs. It is a machine-readable and human-friendly API format that describes REST(ish) web APIs and uses JSON Schema that can be written in YAML or JSON. The standard describes in detail API Authentication, Endpoint, Request and Response Structure, and Set of Error Message regardless of what API is being used. Following such a standard makes the API easy to be used and understood as developers have most likely used other APIs that follow the same standard.
As per the website, RingCentral follows OpenAPI standards and even makes their API spec public on their developer portal that can be referenced when designing your APIs.
3. APIs Authentication & Security to avoid sharing sensitive data inadvertently, policy on how to manage API credentials, etc.
If we look at RingCentral platform, they support 3 popular ways to perform authentication from least secure to most secure (Password Flow, JWT, 3 Legged OAuth with PKCE)
4. Environment (Test, Production): Provide an environment for mock, testing by developers prior to using the APIs in a production environment. RingCentral does this well by providing developers with’ Sandbox’ and ‘Production’ environments.
5. API Gateway to monitor, publish APIs, etc. These can be built in-house or used by one of the popular cloud providers.
6. API Future Planning: Backwards compatibility, Versioning APIs and API specs, automation using CI/CD to generate API docs, SDK, etc
7. API Cost & Monetization: Do we charge developers based on a certain number of API calls or not? How do we measure the billing and metering of APIs?
8. API Performance: Address key performance-related questions ahead of time such as: How will developers consume our API (at scale) easily? APIs requests will put a load on servers and databases, will your system be able to handle that at scale. Will there be Caching? Will the APIs be async/sync or both? What will the API Rate Limiting be like? e.g RingCentral has 4 categories of APIs that limit the number of API calls based on developer needs.
9. API Explorer & Documentation: Well-documented API specifications and generated documentation that should be versioned and easily found and shared across teams act as the source of truth for the team. This generally also includes providing API documentation that is interactive such as Postman collection or Swagger HTML docs where developers can try APIs. OpenAPI specs either as YAML / JSON files can be stored inside the project’s GitHub repository so they are kept up to date. They can be used by CI/CD process to generate documentation, SDK, etc.
10. API Automation: Lastly, you can make your job a lot easier if you just follow the Standards and use automation from designing the API Schema to developing APIs for developers. OpenAPIs can be fed to documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. A comprehensive list of these tools can be found in this GitHub repository.
Hope this article provided you with insights on how to design and implement better APIs in order to provide an excellent developer experience. If you have any questions or comments, please feel free to post the below.
