How do we Design Platform API - Part 1
Status
Published
date
slug
how-do-we-design-platform-api-part-1
status
Published
tags
system design
platform
summary
How to start The Role of APIs in Platform Ecosystems
type
Post
An API platform serves as a central hub, providing a comprehensive suite of tools for creating, overseeing, and securing APIs in alignment with an organization's API strategy. It enables developers to efficiently navigate the entirety of the API lifecycle within the platform's ecosystem, fostering the development of applications.
For example, Shopify's platform enables developers to craft unique e-commerce experiences with a suite of tools for building custom storefronts and integrating seamless shopping experiences. Meanwhile, Slack's API ecosystem supports building apps that enhance team communication and productivity, demonstrating the power of APIs in transforming workplace collaboration.
The Heart of Modern Platforms
APIs stand as the backbone of digital platforms, enabling them to thrive and evolve. Through APIs, platforms like Shopify and Slack become expansively customizable and integrable, providing the tools necessary for developers to build on their ecosystems. The significance of APIs in the modern digital landscape cannot be overstated—they're the channels through which software talks, shares data, and extends its capabilities.
Take, for example, the prominence of REST and GraphQL. These two have emerged as leading standards for designing web APIs, showcasing the importance of APIs in building robust, scalable, and efficient digital platforms. REST, with its simplicity and well-defined conventions, and GraphQL, offering precise data fetching with reduced network requests, both highlight the diversity in API design tailored to different needs and challenges.
In essence, APIs are not just technical interfaces but the lifelines of platforms, fostering innovation, collaboration, and growth within digital ecosystems.
API Design
As we delve into the art of API design, it's pivotal to start with a clear set of requirements. This foundation ensures that our APIs not only meet current technological standards but also provide a seamless experience for developers and end-users alike.
Key API Design requirements are:
- 🎯 Used across products - company-wide products should use this API.
- 🎯 Unified, developer-friendly Interface - developers shouldn't struggle with API.
- 🎯Available for others - external partners should also be able to use API.
The diagram below shows the example effects of an API Platform based on the above requirements.
Figure 1: General idea of how different products can use the same API as the exposed developer-friendly interface where outside partners can use this API also.
and we do check for requirements checklist:
- ✅ Used across products - since APIs are divided into sub GraphQL APIs we can seamlessly consume API based on our needs.
- ✅ Unified, developer-friendly Interface - implementing GraphQL federation allows us to present a cohesive interface across various services, simplifying developer interactions.
- ✅ Available for others - to cater to a broad spectrum of developer preferences, supporting both REST and GraphQL is crucial. While REST brings simplicity and convention, GraphQL offers flexibility and efficiency in data retrieval.
By design, we consume APIs in the same manner as our external partners. However, thanks to our adoption of the GraphQL approach for data consumption, we can develop state-of-the-art APIs with complex internal logic while maintaining adherence to the foundational principles of API design for all users.
REST
REST API is still the most popular interface for developers and we should take care of that. Even if it adds extra time to maintain two APIs, enhancing the developer experience should remain a priority. By design REST API calls to GraphQL for needed resources and is maintained by Open API specification. For a better experience, the client code is auto-generated as SDK. The Server code is autogenerated as well.
Figure 2: For seamless and less maintenance work REST is calling to GraphQL under the hood.
GraphQL
Thanks to the GraphQL approach for data management we can manipulate them more easily and fit better for API consumption which is our business backbone for others.
Take for example the user data which can be consumed differently - some parts of user fields are available for all consumers and some of them are not. Because we build connections around a graph representation instead of HTTP resources (like in REST) it's very natural.
Figure 3: Example
user graph with protected fields - email and data_cluster.
Scope protection is authorized by the token scope available for the entire platform users. Internal protection is reserved for the platform owner's token scope. Conclusion
In summary, the importance of API platforms is highlighted in this piece. It also emphasizes the role of an API platform in building a culture of innovation, collaboration, and growth within digital ecosystems. Part 2 of this series will provide a practical understanding of REST and GraphQL API's code implementation.