What is an API

API (Application Programming Interface) are like user interfaces but targeted to be consumed by other applications rather than humans.

This interface defines a contract between provider and consumer.

A contract is the exact structure of the request and response

A bit of story: API format

First API format were:

  • XML RPC (Remote Procedure Call)
  • XML SOAP (Simple Object Access Protocol)

Problem

But … XML is heavy in terms of network traffic, so you couldn’t have large payloads crossing over from the webserver to the clients.

XML parsing is CPU and memory intensive

REST Json

Because of previous problems a new exchange format started to be used:

Rest (Representational State Transfer) JSON (Javascript Object Notation)

RESTful

REST stands for REpresentational STate, which means a set of attribute that an object/thing/entity has in a certain moment. This state is managed by a backend system

Rest is not a specific technology, is not a standard

An API is restful when the API has been built using the RESTful architectural style and it follows the principles for RESTful APIs.

HTTP is the preferred protocol to use API with

TYPES OF API

REST API Consumer

  • Private or Internal (part of the same organization)
  • Public or External (outside of the organization)
  • Partner (trusted relationship with the organization)

REST API TYPES

  • Private API, for private consumer
  • Public/External API for public/external consumer
  • Parter API, for partner consumer

There is no particular difference in coding or design these different APIs. What it changes is that they need different aspect in the management of Security, documentation, access request and SLA.

API Security

Private API, consumer are internal and so known (trusted developers). So we can use:

  • Basic auth
  • proprietary schemes

For public and partner API it’s not possible to trust developer, So we can use:

  • key/secret
  • OAuth

Documentation

In case of Partner and private API we are in a “controlled environment”, so no formal documentation

In the public API we talk about uncontrolled environment, we don’t know about unformal documentation, so we need to publish the documentation on a developer portal (which is a good practice also for the other types)

Access Request

for private and partner API, because of controlled environment we can ask it through emails of internal ticketing/process

In case of public API, uncontrolled environment, it’s a good idea to have request for access through a developer portal (which is a good practice also for the other types)

SLA Management

SLA stands for Service Level Agreement, and specifies which service to expect from a service provider and which are the conditions.

Because of API are sort of contracts, consumer and provider has to agree on the quality and condition of the service, for instance up time 99%, throughput 20 calls per seconds and support by email