Introduction To API design
What is an API?
A programmer might make use of a variety of API tools to make the program easier and more straightforward. API stands for Application Programming Interface, which is a set of communication protocols and subroutines used by various programs to communicate. In addition to this, an API also facilitates the programmers with an efficient way to develop their software programs.
So, in a nutshell, an API enables two programs or applications to communicate with each other by providing them with necessary tools and functions. By taking the request from the user and sending it to the service provider, it then sends the result generated from the service provider back to the user.
A developer extensively uses APIs in his software to implement various features by using an API call without writing the complex codes for the same.
APIs can also be created for operating systems, databases, hardware systems, JavaScript files, or other object-oriented files. APIs are similar to GUIs (Graphical User Interfaces) with one significant distinction.
In contrast to GUIs, APIs enable the developers of software to access web tools, while GUIs make a program easier for users to understand.
Types of APIs
There are three basic forms of API-
WEB APIs
A Web API also called Web Services is an API that is extensively used over the web and can be easily accessed using HTTP protocols. A Web API is an open-source interface that can be accessed by quite a few clients using their phones, tablets, or PCs.
LOCAL APIs
Local APIs provide programmers with access to local middleware services such as TAPI (Telephony Application Programming Interface), .NET.
PROGRAM APIs
It makes a remote program appear to be local by making use of RPC’s (Remote Procedure Calls). SOAP is a well-known example of this type of API.
Few other types of APIs are as follows:
SOAP (SIMPLE OBJECT ACCESS PROTOCOL)
It defines messages in XML format used by web applications to communicate with each other.
REST (Representational State Transfer)
It makes use of HTTP to GET, POST, PUT, or DELETE data. It is basically used to take advantage of the existing data.
JSON-RPC
It uses JSON for data transfer and is a lightweight remote procedure called defining a few data structure types.
XML-RPC
It is based on XML and uses HTTP for data transfer. This API is widely used to exchange information between two or more networks.
Above are the various types and forms of APIs extensively used over web networks to exchange information and to enhance communication between them.
Advantages of APIs:
Efficiency
APIs produce more efficient, quicker, and more reliable results.
Flexible delivery of services
APIs deliver services quickly and flexibly according to developer requirements.
Integration
API allows data to be moved between various websites and systems thus enhancing the integrated experience for users.
Automation
It supports automation.
Disadvantages of APIs:
Cost
Developing and implementing API is costly at times and requires high maintenance and support from developers.
Security issues
Using API adds another layer of surface which is then prone to attacks, and hence the security risk problem is common in APIs.
What is a REST API?
REST stands for Representational State Transfer. It is an architectural style for designing complex networked applications (apps that communicate with each other over a network). It is the most popular style for developing web APIs.
In REST, data (e.g. image, video, text, etc.) are viewed as resources that a client can fetch, edit, or delete. The client requests a particular URL, and the server responds with the appropriate response.
Think of it as a contract between the programs: the requester (aka the client) and the responder (aka the server). If the requester sends X to the responder, the responder will provide Y. X and Y are specified in the contract between the parties and explained in the instructions.
REST is stateless, so every request from the client must contain all the information that the server needs to understand. For example, the client cannot assume that the server remembers what they have asked for in the past.
Think of API design as a car, with a steering wheel, brake pedals, and an accelerator. Good API design has some core principles, which differ in implementation. Let me give you an example.
A rental car might have different hazard lights, a different trunk release, or a different radio, but it’s rare that an experienced driver won’t understand how it works.
A great API team strives for “ready-to-drive” APIs — APIs that require very little or no explanation for an experienced practitioner to get started with them.
Principles of API design:
Simplicity
The simplicity of API design is determined by the context. One design may be simple for one use case, but extremely complex for another, so the granularity of API methods must be balanced. It can be useful to think about simplicity on several levels, including:
Data Format
Support of XML, JSON, proprietary formats, or a combination.
Method Structure
Generally, methods can be very generic, returning large amounts of data, or very specific, allowing for targeted requests. Methods are also usually called in a specific order to achieve certain results.
Data model
As a result, the underlying data model can differ greatly from what is actually exposed via the API. This impacts usability and maintainability as well.
Authentication
A developer must be able to easily understand and work with rights and quotas for their work. Different authentication mechanisms have different strengths and weaknesses. The one that works best for the context is determined by usage policies.
Article References:
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
Disclaimer: The views, thoughts, and opinions expressed in the text above belong solely to the author, and don’t reflect views of the author’s employer, organization, committee, or other group or individual.
