Understanding the API-First Approach
The API has become the coolest way to expose business functionality to the outside world. Without an API, a business would be like a computer without an internet connection.
Photos from Instagram can be shared on Facebook, locations can be shared via WhatsApp, and Google Maps can be accessed through the Uber mobile app. Connections are endless. In recent years, public APIs have proliferated, making all of this possible. APIs generate a large percentage of revenue for Expedia, Salesforce, Google, and many other companies.
Web APIs should be adopted by enterprises for five reasons.
- Through API ecosystems, you can attract customers to your products and services.
- By combining APIs from your company and third parties, you can drive innovation.
- Enhance the time-to-value and time-to-market for new products.
- The web API integration can be improved
- Prepare for a flexible future by opening up more possibilities for a new era of computing.
A few very good examples of early entrants into the API economy are Amazon, Salesforce, Facebook, and Twitter.
Originally, Jeff Bezos wrote a letter to Amazon’s engineering team highlighting the following points:
- All teams will henceforth expose their data and functionality through service interfaces.
- Teams must communicate with each other through these interfaces.
- There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared memory model, and no backdoors whatsoever. The only communication allowed is via service interface calls over the network.
- It doesn’t matter what technology is used. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
- All service interfaces, without exception, must be designed from the ground up to be externalizable. This is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
As a result of this API service-based approach, Amazon has been able to easily transform itself from a bookseller to a global retailer offering IT services and cloud computing.
Business Models
API economy success depends on having a proper business model. IBM’s Redbook, The Power of the API Economy, outlines four API business models:
- Free model — The focus of this model is on business adoption and brand loyalty. This model includes APIs from Facebook and Twitter.
- Developer pays model — The API consumer or developer pays for API usage in this model. Only what developers use is charged by Amazon.
- The developer is paid directly — In a sense, this is a revenue-sharing model. Google AdSense is a good example.
- Indirect — In this model, enterprises build a larger ecosystem around it, including Salesforce, Twitter, and Facebook.
API Management
A naked API is any HTTP endpoint that accepts requests and generates responses based on business logic. Naked APIs are unmanaged APIs.
The following are some of the deficiencies of an unmanaged API:
- Business owners of APIs cannot be tracked properly, nor can ownership evolve over time.
- Versions of APIs are not managed properly. The introduction of a new API could possibly break all existing consumers.
- There is no restriction on the audience. APIs can be accessed anonymously by anyone.
- API calls are not limited by time. There is no limit to how many times anyone can invoke the API, which may cause the server hosting the API to run out of resources.
- There is no tracking information at all. Stats will not be collected for naked APIs.
- Scalability issues. It would be difficult to scale APIs based on usage patterns since no stats are collected.
- There is no discoverability. Applications are the main consumers of APIs. Application developers need APIs that meet their requirements in order to build applications.
- There is no proper documentation. Naked APIs will have a proper interface, but no documentation.
- There is no elegant business model. As a result of the reasons listed above, it’s difficult to build a comprehensive business model around naked APIs.
All or most of the preceding concerns must be addressed by a managed API. Consider Twitter API for creating a tweet as an example.
Request
curl --location --request POST 'https://api.twitter.com/2/tweets' \
--header 'Content-Type: application/json' \
--data-raw '{
"text": "Hello World!"
}'
Response
{
"title": "Unauthorized",
"type": "about:blank",
"status": 401,
"detail": "Unauthorized"
}
Twitter APIs are all secured with OAuth 1.0 or 2.0. Even with proper access credentials, you cannot use the API. Within a given time window, you can only invoke the Twitter API a fixed number of times per API call. All APIs with public access must take this precaution to avoid denial of service (DoS) attacks.
Twitter monitors its APIs closely in addition to securing and rate-limiting them. Twitter API health displays the current status of each API. Versions are managed by Twitter using the version number in the URL. New versions of the Twitter API will have a new version number, so existing API consumers will not be affected.
Managed business APIs include security, rate limiting, versioning, and monitoring. For high availability, it must also be able to scale up and down based on traffic.
API Lifecycle Management
Lifecycle management is another key difference between a naked API and a managed API. The lifecycle of a managed API begins with its creation and ends with its retirement. There are four stages in an API lifecycle: Created, Published, Deprecated, and Retried.
In order to promote an API from Created to Published, you need to ensure the API is properly secured, the documentation is ready, and the throttling rules are enforced. In order to turn a naked business API into a managed API, these quality-of-service aspects must be built around it.
A managed API must have a description and be discoverable. API descriptions must be extremely useful and meaningful. APIs must also be published somewhere to be discovered. API management platforms must include three main components: a publisher, a store, and a gateway. API store isalso called developer portal.
Swagger
In order to develop successful APIs, developers must use tools such as Swagger to create better designs and documentation. With Swagger, you design, build, and document APIs using a design-first approach so that web, mobile, and third-party applications can quickly consume and integrate them.
For Swagger to be effective, you must understand the high-level differences between it and OpenAPI. RESTful APIs are designed, documented, and coded using the Swagger toolset and structured approach. OpenAPI specifies a standard format for defining metadata for RESTful web services. Previously known as the Swagger specification, the OpenAPI Initiative is a collaborative working group focused on developing the OpenAPI Specification.
Using Swagger’s toolset, we can define APIs according to the OpenAPI standard. OpenAPI Specification, on the other hand, provides a standard format for describing or defining RESTful web services. Machine-readable metadata can be consumed by tools or systems that understand API definitions adhering to the standard. At a high level, think of Swagger as a set of tools and OAS as a set of rules.
Open-source tools and pro tools make up the Swagger Toolbox. The open-source tools can be downloaded and installed for free. You can use these tools to build API definitions, API documentation, and client SDKs. For API teams building APIs, the pro tools provide a more comprehensive platform with collaboration features. Swagger’s open source tools make it easy to design, document, and define RESTful web services.
The open source toolbox includes three tools: Swagger Editor, Swagger UI, and Swagger Codegen.
- For building API definition files, the editor acts as an IDE.
- API definition files can be consumed by Swagger UI to produce interactive API documentation.
- In addition, Swagger Codegen can generate API clients and server stubs in several languages.
In a future post, we will explore Swagger in more detail.
References
Book — The Power of the API Economy
