Private or public
Internally used — so-called private APIs — are only accessible to developers within an organization. Most often, these APIs are used to connect internal team processes so that work is done less in isolation and collaboration can therefore be optimized.
Public APIs — so-called public APIs — on the other hand, offer external developers a convenient way to access internal company data and then use this information for their own use cases or to connect it with data from other public APIs.
The requirements for a public API are significantly higher than those for an internal API. Quality deficiencies, which may be unpleasant and tolerable with internal APIs, will have a more negative impact on public APIs, as a significantly larger number of developers will use the API.
The quality of the API therefore also has a higher impact on the provider's reputation.
Developing and deploying public APIs is one of our core competencies. We support our customers from design to operation of public APIs. In doing so, we have developed standardized concepts for us that help us solve many problems in advance.
What are the key success factors to consider when designing a public API?
The finished interface should primarily meet the needs of its users. APIs not accepted by developers incur high costs while missing business goals. Once an interface is designed and fully developed, error correction is difficult and time-consuming. You may then have to start all over again: design a new API, implement it via a connection to the applications that provide data, and finally publish it again. Most serious, however, is that they must convert all existing consumers to the new version.
The API must be easy to understand and use. Developers should assess the functionality of the API and be able to use it within a few minutes.
To ensure this, there are a number of principles to follow when developing public APIs.
The focus must be on design. A good API concept makes it easier for application developers to overview the intended use and functionality of the interface.
In addition to user-friendly documentation, this also includes that versioning is comprehensibly regulated.
In order to be able to adequately implement all these requirements, it is advisable to establish company-wide, standardized regulations for public APIs. The use of an API management platform can make this easier. Commonly used platforms include Apigee, 3scale, IBM API Management, Akana or Kong. The differences between the listed API management tools lie primarily in pricing and in some functionalities, which will not be discussed in more detail here.
General functions of an API management platform are:
- API portal: Provides access, control, audit, and documentation
- API Lifecycle Manager: Control the journey from design to completion
- API Policy Manager: Controls policies that help ensure API security
- API Analytics: Reveals metrics that can be used to make informed business decisions
- API gateway: Connect the API provider and consumer
At pentacor, a template approach has proven effective for designing public APIs, which supports requirements analysis at an early stage. This questionnaire clarifies, among other things, the following important details:
- API product name: As an API provider, it is possible to combine several APIs into one product. It is also possible to control access to the API resources in the API product. For example, it is possible to provide different resources that can be accessed depending on the payment model. There is then a product for which every request is billed, as well as a second product, which is billed via a flat rate and allows unlimited access. API products are the central mechanism for authorization and access control to APIs. Every consumer must first register their application in order to access the API product. After successful registration, you will receive an API key that can be used to access the product.
- Authorization: As already mentioned, access control to the API plays an important role so that only authorized access to the APIs takes place. In addition to the already mentioned API key Can you also access it via OAuth 2.0 protect.
- To protect the application from overloading, it is possible to configure a quota check or spike arrest
- Quota check: A quota policy controls the number of requests that an API proxy allows over a certain period of time, such as minute, hour, week, or month. The quota can either be configured globally for all applications that access the proxy, or only for a specific product, application, or consumer.
- Spike Arrest: The Spike Arrest Policy protects against load peaks. This throttles the number of requests that are forwarded from the API proxy to the backend and performance drops and application failures are thus prevented.
- Backend Call Security plays an equally important role. In our projects, SSL/TLS is very often used in communication between the API management platform and the application.
- Monetization: As already mentioned with the API product, it is possible to offer individual products for a fee. Each consumer sends their API key with every request and is therefore uniquely identifiable. This makes it possible to monitor who uses which API and how often. This data can be used for analyses and reports as well as for monetization. In our projects, it has been tried and tested to also offer free access to the API. These allow access to dummy data in a tryout product [1] or a limited number of accesses to real data in a trial product [2]. With these products, you enable the developer to test the API and you don't sell the “API in a sack.”
In addition, easy-to-understand documentation of the API should not be neglected. Of course, you can read many technical details directly from the OpenAPI specification. However, you should also provide so-called user documentation, which contains a detailed description of the individual endpoints offered by the API, which is supplemented by examples.
Finally, it's worth mentioning that an automated process should be used to install the API proxy configurations.
synopsis
To provide a public API, you have to consider many aspects. However, in order to avoid the most common mistakes and problems in advance, it helps to stick to standardized templates during design and development. If you want to take a closer look at public APIs yourself, you can, for example, at https://docs.apigee.com/api-platform/get-started/get-started Set up your own API proxy in apigee's so-called Edge UI as a test. In doing so, you can familiarize yourself with the aspects of public APIs mentioned here in the blog.
[1] A tryout product has the functionality of the real API. However, only static dummy data is accessed.
[2] A trial product is identical to the real API. This gives consumers a certain number of accesses to the real data.
