Application programming interfaces - A holistic view

Some definitions

What is API?

• An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, that offers a service to other pieces of software.
• In contrast to a user interface, which connects a computer to a person, an application programming interface connects computers or pieces of software to each other.
• One purpose of APIs is to hide the internal details of how a system works, exposing only those parts a programmer will find useful and keeping them consistent even if the internal details later change.

API Turns software into Lego bricks

• In the modern world, there are thousands if not millions of APIs dwindling together to form an application. 
• This looks like a software version of the LEGO bricks system that you can put together to create new things.
• Each software brick can be used at the same time by many others and can run anywhere on its own if it is connected to a network to be accessible via its API. 

Architectural Constraints of RESTful API

• Uniform Interface
  • Suggests that there should be a uniform way of interacting with a given server irrespective of device or type of application
• Stateless
  • The necessary state to handle the request is contained within the request itself and the server would not store anything related to the session.
• Cacheable
  • Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side.
• Client-Server
  • A Client is requesting resources and is not concerned with data storage, which remains internal to the server, and the server is someone who holds the resources and is not concerned with the user interface or user state.
• Layered System
  • An application architecture needs to be composed of multiple layers. Each layer does not know anything about any layer other than that of the immediate layer
• Code on Demand (Optional)
  • According to this, servers can also provide executable code to the client. 

Types of APIS

• Private
  • API is solely used within the organization. Apps are mostly built for company employees.
• Partner
  • This API is available for business partners and hence is secured. Software Integration between two organizations
• Public
  • Available to any third party. Apps are mostly designed for end customers for direct consumption. Low on security since information is mostly public.

REST vs. SOAP

• REST and Simple Object Access Protocol (SOAP) offer different methods to invoke a web service. REST is an architectural style, while SOAP defines a standard communication protocol specification for XML-based message exchange. REST applications can use SOAP.
• RESTful web services are stateless. A REST-based implementation is simple compared to SOAP, but users must understand the context and content being passed along, as there is no standard set of rules to describe the REST web services interface. REST services are useful for restricted profile devices, such as mobile, and are easy to integrate with existing websites.
• SOAP requires less plumbing code - meaning low-level, infrastructural code that connects main code modules together - than REST services design. The Web Services Description Language describes a common set of rules to define the messages, bindings, operations, and location of the service. SOAP web services are useful for asynchronous processing and invocation.

API - Must have

Any API should provide documentation.

• Any API should provide its documentation that consists of at least the following:
  • A quick start
  • Authentication information.
  • The explanation for each endpoint.
  • Error information.
  • Example of Request & Response with possible Schema
• The API Definition should be available in the form of:
  • RAML
  • Open API Specification / SWAGGER

API should be restful

• One of the key points is that in a REST API the endpoint should be defined by nouns rather than verbs in endpoints. So, the name of the endpoint should be
  • /employees
    • GET
    • POST
    • PUT
    • DELETE

- rather than -- 

• getEmployee
• createEmployee etc.
• This is because HTTP methods such as GET, POST, PUT, PATCH, and DELETE are already in verb form for performing basic CRUD (Create, Read, Update, Delete) operations.
• Name collection with plural nouns. 
  • /employees instead of /employee
• The RESTful API uses existing HTTP methodologies defined by the RFC 2616 protocol, such as 
  • GET to retrieve a resource.
  • PUT to change the state of or update a resource, which can be an object, file, or block.
  • POST to create that resource; and
  • DELETE to remove it.

Resource-based identifier

• In the case of HTTP, we do not need to send a request body in order to retrieve data from the API. A resource should have an identifier, which is a URI that uniquely identifies that resource. For example, the URI for a particular customer order might be:

https://api.nvidia.com/employee/3003

Resource naming case convention

• It should be a practice to use nouns in the URL rather than verbs, so use GET /employee not GET /getEmployee is not suggested.
• The RFC 3986 specification for URI standards also denotes that URIs are case-sensitive (except for the scheme and host components of the URL). Given the widespread use of it, avoid any unnecessary confusion due to inconsistent capitalization.

https://api.nvidia.com/employeeMaster
https://api.nvidia.com/employeemaster

API should STRUCTURE SHOULD BE CONCISE

• It is important to have a concise structured API rather than building smaller bunches of API. 
• Instead of creating multiple small APIs to manage different endpoints, creating one API with similar business/technical functionality having various endpoints helps the consumer search and consume API easily.

API RESPONSE should be well-organized

• Designing a well-organized API starts with the data, so it is important to have organized data that is easily readable to the client. Take this example. It is important to group similar information using substructure rather than putting all fields in a flat order.

Status codes for Error Handling

HTTP Status code should be always used for response, whether success or error.

• 200 series - Success
  • 200 - Successful Response for GET etc
  • 201 - Successful creation
  • 202 - Asynchronous Processing initiated.
• 400 series - Client-side errors
  • 400 - Bad Request
  • 403 - Forbidden
  • 404 - Not found
• 500 series - Server-side errors
  • 500 - Internal server error
  • 502 - Bad Gateway

Consistent API error response in the case of a hybrid integration platform is key for a business.

API security

• API development has increased astronomically in the past few years, fueled by digital transformation and the central role APIs play in both mobile apps and IoT. This growth is making API security a top concern. 
• It should be noted that not only Authentication and Authorization but there are other various aspects of security to be considered.

1. Access Control:
   1. Authentication
   2. Authorization
2. Content Validation
   1. Schema / Patter
   2. Signature-based threat detection
3. Rate Limiting
   1. Rate limits & quotas
   2. Spike protection
4. Analytics
   1. Geo-fencing and geo-velocity check.

Authentication

• Private
  • 2-way SSL or IP-based validation
  • Client ID + Client Secret validation
• Partner
  • OAuth 2.0-based Authentication using Client_Credential Grant Type
• Public
  • Client ID + Client Secret with Rate Limiting.

Content validation

• Use JSON as the format for Sending and Receiving Data
  • Even though API Supports various methods of transporting data including XML, CSV, etc. JSON has largely become the de-facto format for sending and receiving API data.
• Each POST/PUT API should have a corresponding Schema Validator. This would make sure that certain attacks can be stopped at the API Gateway Level.

What is next?

SOAP - REST - GRAPHQL

• Yet another API style is GraphQL, an emerging open-source API standard project. GraphQL is popular with front-end developers because it puts them in control. They are no longer restricted to a fixed set of API methods and URI patterns but instead get to customize their queries in whichever ways the best suit their applications and context.