Como documentar e aplicar políticas e contratos de API?

API policies and contracts serve as foundational elements that define the rules, expectations, and standards guiding the design, implementation, and utilization of an Application Programming Interface (API). These essential components play a crucial role in ensuring consistency, security, and effective collaboration among developers, organizations, and systems interacting through APIs.

API policies and contracts are vital for ensuring consistent and secure API usage. Documenting these in standards like OpenAPI or GraphQL helps define clear boundaries and expectations, which can be automatically enforced using tools like API gateways and schema validators to maintain integrity and performance.

To document and enforce API policies and contracts, I start by defining clear guidelines for how the API should be used, including rate limits, authentication, and data access rules. I use tools like Swagger or Postman to document these policies, making them easily accessible to developers. For enforcement, I implement validation checks within the API code and use monitoring tools to ensure compliance, helping maintain consistent API behavior and reliability.

One of the best embedded documentation tools / contract guidelines mechanisms within the API responses is HATEOAS (Hypermedia As The Engine of Application State). HATEOAS allows a developer to use the endpoint itself to 1) see navigational links to traverse the aggregated entities, 2) understand the schema of the entity, and 3) see sticky links/URLs for the called API in its response objects. HATEOAS provides invaluable embedded help to developers to learn about the endpoints and API structure, without making them leave their favorite API integration tool or IDE.

API can be loosely thought of as an exchange, where you can exchange data. There are some rules and regulations that governs the exchange. A sample exchange rule can be: To get the number of employees as an integer for a department from an API, you need to send a request with a payload that has the department name, and a header that has a token with authenticates the request and authorizes it to use the API.

They are important because they set the standards to be followed in the organization and keep the coherence and consistency of the API Ecosystem aligned with business.

API policies and contracts serve as a framework for quality, security, and collaboration. They establish clear guidelines and enable robust version management, making it easier to communicate changes and ensure compatibility across different versions. This fosters better integration and reuse within the API ecosystem.

All of below should be part of api-definition/deployment Secure by default for Internal Services/Clients for External Services/Clients Header enrichment + cleanup Mock versions from day-1 Help quickly play around ( until Prod ) Help QA Automation Level-3 REST ( HATEOS ) Support end-to-end persona that entity support via api Api-Gateway to also support Rate-Limits ( Local / Global ) Groups / Pages / Targets Custom Plugin scope JSON import/export base api deployment API based deployment on api

In addition to API quality and consistency, policies and contracts help with predictability. Your API consumers can evaluate whether they want to consume your API more effectively and have a better idea of what to expect when they do so.

You should place special emphasis in your documentation on how to authenticate with the API. It is critical to clearly detail the way in which you get whatever tokens or credentials required to authenticate, as well as how to present those when using the API. Authentication is often the first hurdle facing any developer intending to use your API, and in my experience, is often the biggest pain point. This is especially true if your API authentication is non-standard or has some proprietary peculiarity. If you are building a new API, strongly consider using an authentication scheme such as OAuth2.

Using standardized specification formats like OpenAPI, RAML, or GraphQL ensures that API documentation is both human-readable and machine-processable. Tools like Swagger and Stoplight enhance this by enabling easy editing, validation, and sharing of API contracts, streamlining collaboration and consumption across different stakeholders.

OpenAPI / Swagger Mostly Auto generated from the code annotation JSON / YAML works Share working copy via Postman files with environment files, sample body payload per-populated, Postman files committed in the code repo.

OpenAPI is the best way to document your API policies and contract - as many of the fields align with them. Terms of service, contact links, etc are all fields in OpenAPI. One notable exception is the inability to disclose rate limits, however that can easily be covered in the top level description in your OpenAPI spec. Other contracts like operation schemas and response formats can be documented at the operationObject level. Lastly, policies like authentication are self-evident in most specs through the securitySchemes property

There are many ways of doing this. Let me mention the most common ones, although it is possible to find other approaches. For syntactic validations, Spectral is king. Once you've defined your standards in the form of a ruleset, you can run a script that will give you where in your API there are ruleset violations so that you can correct them properly. For semantic validations, you can use GenAI integrated with Spectral to analyze the content of the fields and whether they make sense. Finally, you can use API Management Platforms to enforce runtime policies such as security, traffic shaping, throttling, and so on.

From my experience, effectively enforcing API policies and contracts often involves using an API gateway or service mesh like Kong or Apigee. These act as intermediaries, applying necessary policies such as rate limiting and authentication, and ensuring adherence to API contracts. Additionally, tools like Spectral for syntactic validations and GenAI for semantic checks have been invaluable. They pinpoint areas needing correction, ensuring your API meets defined standards. API Management Platforms are also crucial for runtime policy enforcement, managing security, and traffic. Each of these components plays a distinct role in creating a robust, policy-compliant API ecosystem.

API gateways and service meshes like Kong, Tyk, Apigee, and Istio are crucial for enforcing API policies and contracts. They manage access and traffic, ensuring compliance with defined specifications by dynamically applying rules like rate limiting and authorization, and verifying interactions against API contracts.

For API docs on our team, we use tools like Swagger or Apigee that make the contract very clear. For enforcement, we use automatic testing tools like Postman or Pact to make sure the API follows the terms of its contract. In the API code, rules like rate limits and authentication are applied automatically. To set rate limits for certain paths, as an example, we could use middleware in Express.js.

API gateways act as the entry point for the API's and enforcing API policies and contracts at the entry level is key to secure and make API efficient.Many popular API Management tools come with so many OOTB policies which can be leveraged and enforced on the API's very easily.There are SDK's to build custom policies as well.API Management tools provide options to create contracts for different consumers and define SLA's if required.I have used Mulesoft's Anypoint platform which provided these features and is among the Gartner's Top pick for API Managment.

Especially when your API Ecosystem is huge automation is mandatory, otherwise, executing tests by hand will be expensive in time and resources. Tests should be run during the first stages of the API Lifecycle. The sooner the API fails, the better. As per toolsets, general-purpose tools can be found easily, such as Postman. There are also more vertical tools such as MockBank for Open Banking and Banking APIs.

Automated testing tools like Postman, SoapUI, RestAssured, and Karate are pivotal for ensuring APIs meet their policies and contracts. These tools use API contracts as blueprints to generate and execute tests, checking for compliance with functionality, performance, and security standards, thus streamlining the validation process.

Using an OpenAPI powered gateway (ex. Zuplo) is the best way to ensure that live traffic flowing to your endpoints is conforming to your policies and contracts. You can compare the incoming request bodies and outgoing responses to your documented ones to ensure conformance

Observability tools like Prometheus, Grafana, New Relic, and Datadog are essential for monitoring API policies and contracts. They provide insights into API health, performance, and usage, and alert on policy or contract violations, helping maintain consistent API reliability and security.

The best way to monitor APIs is by using the API analytics bundled with the API Management/Integration platform you'll be using.

The API contracts being machine-readable are a huge advantage in regards to scanning for policy enforcing. Linting mechanisms could be leveraged to specify the list of rules and may be integrated as part of the continuous development cycle and used as a way to monitor the API specifications. Another benefit of this approach, beyond the automated monitoring of contracts, is the ability to generate, for documentation purposes, a catalog of rules based on the specified policies, serving as a single source of truth.

Monitoring API policies and contracts is crucial for ensuring the reliability, performance, and adherence to specified terms. Observability tools and platforms play a pivotal role in this process by providing insights into the behavior and usage of your APIs.

API Monitoring tool bundled with API Management tools provide valuable information on analyzing the usage and performance of API. Mulesoft's Monitoring tool provides insights on how many request were failed due to policy violation and from which geographic location it were targeted from. The monitoring tools play a key role in analyzing the effective ness of policies and contracts.

In order to record API policies and agreements comprehensively, it is important first to state and elaborate on rules of utilization, handling of data, authentication, and rate limits. Comprehensive documentations with examples can be done using Swagger/OpenAPI tools. Access controls, rate limiters, and standard error handling can be applied in enforcing policies. Automated as well as manual ways such as checking for compliance or simulating violations can be used in testing APIs. Logging, analytics and alerts are part of monitoring tools that help keep records on usage patterns thereby ensuring compliance with the laid down laws.

Documenting and enforcing API policies and contracts is crucial for maintaining consistency, security, and reliability in your API ecosystem. Few things that we diligently follow are : OpenAPI Specification: We use OpenAPI Specification to describe the API in a machine-readable format. This allows for automated generation of documentation, client libraries, and server stubs. Contract Definitions: We clearly define the contract between the client and the server. Versioning: We clearly define the API versioning strategy, and communicate how clients should handle version changes.

In addition to API design guidelines, industry standards such as ODATA or GraphQL, design languages to enforce contracts, or an inspection tool to verify endpoints - it is prudent to scrutinize the data contracts and protocols usage as well. Not everything needs to be an HTTP/S based REST or GraphQL endpoint. Inter-service communication, long running operations, large payload endpoints, or chatty endpoints may be better served with binary channels and persistent TCP connections. Some examples of this includes gRPC with protocol buffers or WCF service models with TCP binding carrying serializable binary objects.