Application programming interfaces (APIs) enable computer programmes and services to communicate with one another and access data. API protocols set out the instructions, formats and techniques that they use to do so. We explore some of the most popular API protocols below, examining how you can use them to interact securely with online data and services.
What are API protocols?
API protocols define the rules around how APIs work, how they send calls and responses, how queries function, how errors are handled and more. They enable developers to work within a framework with set expectations and boundaries that define standards for how the API will function and how it can be consumed.
The most popular API protocol in use at the time of writing is REST – representational state transfer. Other common API formats include SOAP (simple objects access protocol) and GraphQL, which has risen in popularity in recent years.
The API types that developers choose to use will determine the way in which they can design those APIs and how they will function, as well as how easy they are to consume. The different types of API protocols can also impact performance, meaning that this needs to be a consideration when it comes to architectural decisions, particularly around issues such as microservice gateway and access patterns, where organisations are typically looking to move faster.
Different types of API protocols
One of the benefits of Tyk is that it supports REST, GraphQL, TCP and gRPC protocols, providing you with plenty of flexibility when it comes to designing and publishing your APIs. But how do you know which API protocol is best for meeting your business needs? Let’s look at some of the most popular options…
REST APIs
RESTful APIs are APIs that employ the REST protocol. REST APIs are lightweight, versatile and quick and easy to implement, which means they are ideal for scalability. With this protocol API communication takes place over HTTP/HTTPS.
REST APIs are stateless, requiring distinct GET requests with no client data stored between them. REST API requests includes an endpoint (destination URL), method (GET, PUT, POST or DELETE), headers (detailing the request and the required response format) and body (the data).
Each time a request is made, REST assigns it a unique URL, with standardized representations used to transfer the response back from the server (hence the name – representational state transfer).
APIs created following the REST protocol feature the following:
- Client-server separation – requests and responses are simple, back and forth interactions.
- Uniform interface – requests and responses use common formatting for standardised communication.
- Stateless – each request is distinct, as is its response, with the server not required to connect or remember the different requests.
- Cacheable – the client can cache API responses to support faster response times.
- Layered – there is separation of concerns between the API frontend, backend and server, making it easier to make changes to the backend without impacting anything else.
Many RESTful APIs also feature code on demand. This means that the server can send a response containing code that the client can execute (rather than data). However, the potential for exploitation of code on demand means that this is an optional characteristic with the REST protocol, rather than an essential one.
GraphQL APIs
According to the 2022 State of GraphQL Report, 19.5% of developers are now using GraphQL for publicly available APIs intended for third-party developer consumption, while the figure rises to 40.4% for private unexposed APIs for internal usage and to a massive 47.9% of developers for APIs for personal websites or apps.
Suffice it to say, if you’re contemplating creating an API, GraphQL warrants consideration, particularly if you’re working with microservices. By implementing an API gateway for microservices with GraphQL, you can deliver a highly performant solution that gives you both security and control
A GraphQL API requires three core components: a query, a resolver and a schema. The query is the request that comes from the GraphQL client to the server, specifying what information is required, using fields and arguments. The resolver provides the instructions for turning the resulting GraphQL operation into data. The schema, meanwhile, uses types to bring everything together by describing the available functionality and data.
GraphQL APIs use queries to request the data they need. With data described in the schema, the client can then ask for what is required, producing predictable results.
APIs created using the GraphQL specification may (but don’t have to) make use of the following common best practices:
- HTTP – while REST APIs rely on single instance URLs, GraphQL usually uses a single endpoint over HTTP.
- JSON – usually, GraphQL services respond using JSON, due to how well JSON can compress with GZIP.
- Versioning – as it’s possible to continually evolve the schema, there is a decreased need to version GraphQL APIs, meaning it’s easier to avoid breaking changes.
- Nullability – every field is nullable by default in a GraphQL type system.
- Pagination – API designers have control over the pagination of lists of values that some fields can return.
- Server-side batching and caching – developers can use batching techniques to collect multiple requests for data over a short time period and then dispatch a single request.
SOAP APIs
The SOAP web service protocol is an open standard that uses XML data formatting to enable communication via the internet. It predates REST, having been created in order to facilitate data sharing between applications.
SOAP APIs use envelopes that define message structures and processing details, along with encoding rules and call and response conventions. They have three notable characteristics:
- Extensibility – developers can introduce features via extensions.
- Neutrality – SOAP operates over HTTP, UDP, SMTP, TCP and JMS, providing plenty of flexibility.
- Independence – SOAP APIs are language-independent and platform-independent as their responses use XML.
While many web applications rely on REST (and more recently GraphQL), SOAP APIs form the foundation of many large corporations’ operations. Thanks to the robust security resulting from SOAP’s use of WS-Security and SSL for transmissions, SOAP APIs are also popular with government organisations, banks and other large businesses where security is a top priority.
gRPC
Available publicly since 2015, gRPC is a cross-platform, contract-based remote procedure call (RPC) framework. It is open source and communicates using HTTP/2 and TLS.
Characteristics of gRPC APIs include binary payloads, bidirectional streaming and protocol buffers. The latter includes a contract definition language, accessor-function code and language-specific runtime libraries. Developers can define functions and parameters within API protocol buffer files.
gRPC is lightweight and fast (compared to REST), meaning that many large organisations make use of it, including its creator, Google, which used gRPC to connect microservices as far back as 2001. In addition to being useful for microservices architectures, gRPC works well when connecting mobile clients with backend services.
RPC APIs
Like SOAP APIs, RPC APIs predate REST. RPC APIs are particularly useful for single actions or tasks, rather than handling large volumes of data. They rely on TCP or UDP to function correctly, with UDP delivering better performance.
RPC APIs use a query-response loop to fulfil calls and requests. The call goes from client to server, with the response shipped back synchronously.
There are two main types of RPC API, so let’s take a quick look at each of these.
JSON-RPC
JSON-RPC is designed (as the name implies!) using JSON. JSON-RPC APIs are lightweight, stateless and easy to implement.
XML-RPC
XML-RPC APIs, meanwhile, transfer data as XML files. This means they are more secure than JSON-RPC APIs, so are beneficial to organisations where security is a priority.
API protocols and architectures
Deciding which API protocols to use will be part of a wider business strategy that looks at which API management architectural and deployment patterns will best serve your company’s operational goals. Understanding your particular balance between security, speed, flexibility and more will help feed into discussions about which API formats will be the most suitable.
Each API protocol has its own distinct advantages and uses, which is why there isn’t a ‘one size fits all’ protocol in use by every organisation. At the same time, new technology and business trends – notably, the huge proliferation of software-as-a-service (SaaS) business models – is driving new ways of thinking about APIs and their use. This is why such careful attention needs to be paid to using the right API protocol to meet your business needs.
Such decisions also depend on the intended use of your API. If it’s a web service protocol you need, for example, then RPC would not be as suitable as REST (for example). Yet if it’s a lightweight approach to interacting with a network that you need to enable, RPC might be the better choice. Whether your API is internal, external, public or composite will also play into the thinking around which API protocols and architectures are best.
For long-established businesses, it’s also important to consider which API protocol will play most nicely with your existing infrastructure. Legacy systems can create complexities for businesses pursuing digital transformation strategies, so must be factored into any decisions around new protocols and architectures.
What is the difference between API protocols?
The API protocols we have explored above have fundamental differences from a technical perspective. The result of these differences can be seen in:
- Performance
- Functionality
- Reliability
- Ease of implementation
- Ease of consumption
- Security
- Scalability
There is often a need to balance which of these are most important to a business’ operations when it comes to API-related decisions. Performance tends to be a top priority when it comes to GraphQL APIs, for example, while reliability is a key attraction of RESTful APIs. SOAP APIs, on the other hand, hold major appeal from a security perspective, although they are more heavyweight that JSON-RPC APIs and some others. SOAP APIs also aren’t the easiest to adopt in terms of the knowledge your team will need to get started.
Choosing the right API
All of the above differences warrant consideration when it comes to choosing the right API for your business. Cost will also come into play, of course. Decisions around the different API protocols will impact everything from the breadth of the developer resource pool you have to choose from to the time it takes to get your product to market.
API management is another consideration. The API protocol you choose will dictate which API management solutions you can implement. If there’s a particular open source API gateway or management platform that you plan to use, as you want to benefit from its extensive features or great price, look into how well it will function with your chosen protocol before you commit to anything.
If you have any further questions about APIs, API management and what will work best for your business, remember that the Tyk team is here to help. Why not get in touch to discuss your needs with our friendly experts?
