An API (Application Programming Interface) defines how the features and services in one software system can be accessed by another.
An API definition is a standardised description of the API and its structure – it defines the available endpoints, request and response data structures, authentication mechanisms, and more. It is intended to be machine-readable and used by automated tools, for example, in a CI/CD pipeline.
Why is an API definition important?
Having a well-documented API definition is crucial for several reasons. It facilitates:
- Developer onboarding and adoption. With a clear, up-to-date definition, developers can easily understand what services are available via the API and can start building applications faster.
- Collaboration and governance. Teams working on the same API can coordinate better with a shared definition serving as the single truth source. API changes can be managed through a defined review and release process.
- Improved testing and monitoring. Automated tests and analytics tools rely on knowing exactly how an API is structured and what data it returns. An accurate definition ensures these processes work correctly.
- Scalability and stability. Performance and security issues can be prevented when the full scope of the API and its potential uses are defined from the start. Support levels and SLAs can be established as adoption grows.
What does an API definition contain?
The API definition documents the technical specification of the API, providing the information required to interact with it, such as:
- Endpoints: these are the locations (typically URLs) within the API with which a client can interact.
- Operations: these are the actions (also known as methods, for example, GET, POST, PUT, DELETE, etc.) that can be performed with the Endpoints.
- Data formats and schemas: the structure and format (e.g. JSON, XML) of requests sent to and responses received from the endpoints and data models used within the API.
- Authentication and security: the mechanisms for authenticating users or systems and ensuring secure access to the service exposed by the API.
- Rate limiting: protect the performance and stability of the service by defining usage limits and rate throttling mechanisms.
An API definition can also include human-readable documentation such as usage guidelines, support contacts, changelog, and supplementary documentation to help developers be successful.
How is an API definition used?
As explained, the API definition encapsulates the instructions for consuming the API to interact with the service(s). Whilst this is convenient for the application developer to use directly (for example, when constructing requests to the API and handling the responses), it can also be used to configure elements of the technical stack – in particular, the API gateway, a software component often deployed to manage access to one or more APIs.
There are many different closed- and open-source providers of API gateways (such as Tyk, Apigee, Mulesoft and Kong), each of which is configured and operates differently, but all of which provide a proxying service where they can receive and manage requests to the APIs exposed by the upstream services, providing security, rate limiting, analytics and many other features. Visit Tyk’s documentation for detailed insights into how Tyk handles API definitions.
What are the most common formats and specifications for defining APIs?
Several formats and specifications are commonly used for defining APIs. Each has its syntax, structure, and set of tools that developers can use to create, document, and interact with APIs. Some of the most commonly used API definition formats include:
- OpenAPI specification (OAS): Formerly known as Swagger, this is the most widely adopted open standard API description format. OAS uses YAML or JSON to define RESTful APIs. OpenAPI provides a standardised way to describe the endpoints, operations, request/response formats, parameters, authentication methods, and more.
- GraphQL SDL (Schema Definition Language): GraphQL, an alternative to RESTful APIs, uses a Schema Definition Language to define the types, queries, mutations, and subscriptions an API supports. The SDL serves as a contract between the client and server, specifying the capabilities of the API.
- WSDL (Web Services Description Language): WSDL is an XML-based format used to describe SOAP-based web services. It defines a web service’s operations, messages, bindings, and network endpoints.
- gRPC (google Remote Procedure Call): gRPC uses protocol buffers (Protobuf) as its Interface Definition Language (IDL) to define APIs. It enables efficient communication between services and supports multiple programming languages.
- AsyncAPI: Similar to OpenAPI but focused on event-driven architectures, AsyncAPI is used for describing the structure of messages and events in asynchronous APIs (such as MQTT, AMQP, etc.).
- Postman collections: While not a formal API definition format, Postman Collections are JSON files generated by the Postman API development environment. They contain API requests, responses, headers, and other information used for API testing and documentation.
Each standard format serves as a blueprint (blueprint was also the name of an older API definition format) or contract used to define how to interact with a service through an API. They provide a structured way to document APIs, help facilitate better collaboration among development teams, and enable the generation of client SDKs, testing frameworks, and other tools to interact with the API. Choosing the most suitable format often depends on the requirements, preferences, and technology stack used in a project.
Elevating API efficiency
By aligning with industry-standard API definition formats, modern API gateways like Tyk empower developers and organisations to streamline their API workflows from design to deployment, ensuring reliability, security, and scalability within their systems.
Want to learn more about OpenAPI specification? Head over to the blog 10 essentials when creating an OpenAPI Specification. Are you curious about OpenAPI Specification support in Tyk? Head over to our OAS documentation.
