API Management Best Practices

Introduction

This document covers the general guidelines that can be used as best practices when implementing API Management Solution. Customizations can be applied as per use case and organizational demands.

API Management

API management is the process of publishing, documenting and overseeing application programming interfaces (APIs) in a secure, scalable environment. The goal of API management is to allow an organization that publishes an API, to monitor the interface’s lifecycle and make sure the needs of developers and applications using the API are being met.

API Management primarily focuses on,

• Building a smaller set of coarse-grained APIs that are to be exposed to primarily external consumers, but also more often internal consumers

• Configuration of these APIs with regards to security, traffic management and monetization aspects

• Exposure of the API documentations in a simple to use developers’ portal

• On boarding and management of consumers through the developer portal

• Analytics about the runtime usage of APIs to derive usage trends for consumers and providers

API Best Practices

APIs can be SOAP or REST based APIs. REST is preferred for modern APIs because of its simplicity and usage. Below are some common guidelines for REST APIs.

API Design

API design must follow standard REST or SOAP guidelines. APIs should adhere to an organization’s functional and non-functional design principles.

• An API should be coarse grained in nature

• An API should follow a domain-oriented design approach

• As the API might be used by unknown developers outside the organization it should be easy to understand and easy to use from design to documentation

• Avoid exposing internal technical APIs as these might often require a deeper understanding of internal data models and structures

• APIs should be very much self-contained within their domain

• APIs should be designed to support versioning and new features should be added in new versions of APIs

• As APIs might be used in mobile scenarios, avoid chatty APIs that require too many roundtrips between App and API. Balance on the other side with response sizes the API sends back

• Recognize REST best practices in terms of how to structure and name resources of the API

• Use HTTP verbs following best practices to simplify understanding of an API. Examples,

  • Do
  • GET /customers/ for getting details about one customer
  • POST /customers to create a new one
  • PUT /customers/ to update an existing one
  • DELETE /customers/ to delete an existing one
  • Don’t
  • GET /customers/?command=delete - use HTTP verbs to indicate the demanded actions
  • POST /customers to fetch data about all customers

• APIs should preferably use query string for filtering and pagination

• API Idempotence should be maintained –
  
  
  Idempotence definition: Idempotence essentially means that the result of a successfully performed request is independent of the number of times it is executed. For example, in arithmetic, adding zero to a number is an idempotent operation.

API Implementation

The following guidelines are to be followed when implementing APIs,

• In naming REST APIs use nouns instead of verbs for resources

• User plural nouns for collections

  • /rest/apigateway/applications
  • /rest/apigateway/apis

• Use HTTP methods to operate on the resources (GET, POST, PUT, DELETE)

  • Use HTTP GET for read access
  • Use HTTP POST for creating new resources
  • Use HTTP DELETE for deleting resources
  • Use HTTP PUT for updating resources

• User Camel case for resource names

  • Ex: /accessTokens

• Always Include a Mandatory Version Number in URLs

  • Ex: /v1/employees

• Return errors details in response body. This will help users debug

  • Ex:

{

"error": {

"message": "Message describing the error",

"type": "OAuthException",

"code": 190,

"error_subcode": 460,

"error_user_title": "A title",

"error_user_msg": "A message",

"fbtrace_id": "EJplcsCHuLu"

}

}

• Return meaningful response codes

  • Use HTTP 200 for successful execution
  • Use HTTP 201 for successful creation
  • Use HTTP 204 for successful deletion
  • Use HTTP 400 to indicate a bad request
  • Use HTTP 401 to indicate authentication failure
  • HTTP 500 indicates a server error. It should only be used to indicate server problems.

API Governance Best Practices

Design Time Governance

Below are general best practices used in Design Time Governance.

• API should be designed with Design First approach – i.e. defining the API contract first in API Gateway and followed by the implementation

• APIs should have Life-cycle management established centrally– standard API Lifecycle will be Created, Deployed and Deprecated

• API permissions - must be fine grained to control who can see published APIs. Ex: the URI and resource details should not be visible for everyone. However, the API details and documentation should be visible in search

• Approval management – APIs can go through approval workflow during Design phase. The approvers can be Architects (to validate the API contract and design principles) and project managers (who can authenticate the creation of the API)

• User Management – Different personas should be created in API Management platform according to roles in the Organization. Ex: API Providers, Consumers, API Administrators, Developers etc. Each of these personas must be assigned the permissions/functional privilege as per their role

• APIs should be discoverable – APIs must be catalogued appropriately thus making it easily discoverable. API providers should be able to search for APIs before creating their own APIs

• Versioning of the APIs should not be tedious and backward compatibility should be maintained.

Run Time Governance

Below are the general best practices used in Run Time Governance.

• APIs should be grouped by their runtime enforcement needs and clusters of APIs should be built.

Ex: of such groups are,

• APIs with strong authentication/authorization needs
• APIs underlying traffic restrictions

• APIs with special logging requirements

  • All APIs should be Access controlled i.e. they should be accessible only to subscribed clients
  • APIs should have subscription approval workflow established and there should be a group of individuals assigned as responsible for approvals. The approval workflow should be centralized as much as possible
  • API should can be Rate limited through throttling policies
  • Business APIs should be invoiced using API Packages and plans
  • API deprecation guidelines should be established to ensure API Consumers migrate to latest version. The API deprecation strategy along with sunset period should be published in API portal
  • API consumer details such as expiration of API Keys, OAuth token refresh interval etc should be set depending on the criticality of data shared by the API
  • API run time governance should address monitoring, auditing, and metrics collection of an API.

API Policies

Run time governance is dictated by usage of the policies. Below are the standard practises for Polices:

• Policy templates can be created for group of APIs. Policy template can contain multiple policies and can be used across APIs

• Common policies that are used for multiple APIs should be designed as global policies

• Avoid using API local policies unless explicitly needed

• Global and local policies are merged together on deployment

Global Policies

The below are few of the recommended global policies.

• Policy for logging: Logging policy can be set up as global policy and the general recommendation is not to log incoming or outgoing payloads

• Policy for Identifying Consumers: Identify Consumers is recommended to be used for efficient SLA monitoring and reporting.

Depending on use cases more global policies can be created.

API Providers Best Practices

Below are guidelines for API Providers,

• API providers should create the APIs with developer focus. i.e. the APIs should be self-sufficient and well documented

• API definitions should be provided in industry standard formats like Swagger, RAML or Open API specs

• API providers should maintain stable contract for APIs and should preserve backward compatibility when releasing new versions

• API providers should design APIs with flexibility of versioning - i.e. developers should be able to upgrade to new versions without much of recoding

• API providers should design APIs with flexibility of inputs – i.e. APIs should be able to consume and provide payloads in standard formats like JSON, XML etc. allowing the developers to use their choice of payloads

• API providers should enable API mocking for developers to try and test API before subscribing for it

• API providers should use data masking policies to mask sensitive data getting displayed in logs or analytics in API

• API providers should use monitor service performance and/or monitor service level agreement policy to collect SLA data for the API analytics

• API providers should ensure appropriate security mechanism is used for API. Ex: API Key, OAuth, Open ID Connect or JWT.

API Consumers Best Practices

Below are general guidelines for API Consumers,

• API consumers should always use HTTPs when available

• API consumers should expect deprecations of APIs and should design their apps with ease of upgrade to newer versions

• Use HTTP codes efficiently – APIs are designed to send HTTP codes for each status. These HTTP codes should be used efficiently to debug an application

• API consumers should not share API credentials across APIs or with their peers

• API consumers should promote community collaboration by providing valid feedback and ratings to APIs.

API Administrator Best Practices

API administrators are responsible for creating and enforcing policies, maintaining API Lifecycles, user management and mandating API governance. Below are general guidelines for API Administrators,

• API administrators must ensure the API governance is centralized. i.e. the policies are created and enforced centrally through the organization

• API administrators through policies should ensure that APIs developed in the organization are standard and consistent. i.e. API Contracts, documentation and lifecycles should be automated via policies and should be trackable

• API administrators should set up approval workflow for API consumption

• API administrators should create users and groups and assign functional privileges as appropriate. For example, API Provider group should have Manage APIs, Activate/Deactivate APIs, Manage Applications privilege and API Administrator group should have Manage User Administration, Manage destinations, Manage security configurations priviledge

• API administrators should ensure the API management platform is secured. Below are the key security policies that must be implemented

  • All incoming requests must be via HTTPs. HTTP should be denied by default.
  • Trusted IPs should be whitelisted
  • Threat protection policies to prevent against – large recursive payloads, SQL injections, JSON and XML threat protection should be configured.

• API administrators should extract analytics reports at regular intervals representing how many APIs are deployed, the individual and aggregated API usage statistics, consumer distribution, API SLAs etc.

Promotion of APIs

APIs and related assets developed need to be promoted to testing environments and finally to production.

To support promotion multiple options are available:

• Redo everything on every stage (Example, recreate the APIs and policies)

• Export them from the UI using export/import functionality

• Export them from command line using export/import CLI tools

• Automatically deploy using Deployer and Asset Build Environment

Which option is to be used partially depends on environment constraints (i.e. networks). It is not advisable to redo APIs and related assets on each environment.

General Guidelines,

• Ensure that all environments are on the same release level and patch levels

• Always promote upstream, not downstream and under no circumstances in all directions

  • If you have modified asset types (standard or custom) then the asset types are part of the export archives
  • Choose one instance as master for those type definitions and promote from there (ideally dev instance)

Run time data handling

One of the key considerations at the very beginning is to define a strategy how to deal with runtime data. Runtime data relates to Runtime Policy Events and Runtime Performance Metrics that API Gateway produces. In general, the following configuration choices exist:

• Runtime Policy Events and Performance Metrics

  • API Gateway
  • API Portal
  • CentraSite
  • Digital Events
  • Elastic search
  • Email
  • JDBC
  • Local Log

It is important to also understand some characteristics about the different types of runtime data.

• Runtime performance metrics are the aggregated performance information (min/max/average response times, availability) aggregated over all consumers for one API in a configured reporting interval. The reporting interval and the collection of the metrics are a global setting applicable to all APIs deployed to API Gateway. This means low reporting intervals and a large number of deployed APIs will cause a higher volume of data to be persisted. As the information for runtime metrics are highly aggregated one should consider not using to fine grained reporting intervals. 10minutes or up to 60 minutes might be sufficient for many scenarios.

• Runtime events are configured through runtime policies and different policies emit different types of runtime events. In general, most policies only emit events in case of policy failures. But these events will be produced per invocation/failure. Extra care has to be taken with the Log invocation runtime policy action which allows logging of each and every request incl. payload. This policy can cause a massive data growth in high volume scenarios.

Considerations for defining an optimal strategy for handling runtime data include:

• Amount of data expected

• Data retention policies

• Reporting/Dash boarding/Analytics requirements

• Backup and housekeeping procedures

Read full topic