APIs

 


APIs and REST

Application Programming Interface (API)

A server that you can use to retrieve and send data using code.

It enables two pieces of software to communicate with each other, and its most commonly used to retrieve data.

Just like other network services, the API listens on a given port and URI. To which you target your requests.

URI syntax diagram

Definition of Interface:

A shared boundary across which two or more separated components of a computer system exchange information.

REpresentational State Transfer (REST)

REST is a framework… an API framework. REST APIs involve requests and responses over the HTTP protocol.

graph TB;
    A[Web Application]
    B[REST API]
    A--Request-->B;
    B--Response-->A;

“RESTful” design pros

  • Meets performance needs
  • Scales well
  • Simple to write and use
  • reliable

A web service is a defined interface that two systems can use to communicate

Example URI from the Google Maps API:

http://maps.googleapis.com/maps/api/geocode/json?address=sanjose
Part Value Description
Protocol http:// or https:// Indicates if the server host is open or secured
Domain-Name maps.googleapis.com Domain name of the target host
Resource Path /maps/api/geocode/json Resource path of the API call
Parameter ?address=sanjose Details for the service to filter, scope, or paginate the response data.

HTTP methods

REST design centers around the HTTP request and response model.

HTTP request methods

Enter Create Read Update Delete (CRUD), the four basic functions of persistent storage.

Operation SQL HTTP verb RESTful
Create INSERT PUT / POST POST
Read (Retrieve) SELECT GET GET
Update (Modify) UPDATE PUT / POST / PATCH PUT
Delete (Destroy) DELETE DELETE DELETE

Response status codes

When a request that contains a correct URI and verb, the service returns a status code.

A valid REST API request typically gets a 200 OK response, this indicates that the API received and understood the request.

An invalid request might come back as 404 Not Found

List of common REST API status

Status Code Message Meaning
200 OK Received and understood
201 Created New resource created
400 Bad Request Request was invalid
401 Unauthorized Authentication missing or incorrect
403 Forbidden Understood but not allowed
404 Not Found Resource not found
500 Internal Server Error Something wrong with the server
503 Service Unavailable Server is unable to complete request

REST API Headers

Requests and responses can use headers to pass info to or from the service.

These headers can carry metadata to help define request or response.

Header eg Purpose
Content-Type Application/json specify format of data in body
Accept Application/json specify requested format for returned data, in this case json
Authorization Bearer DDuiDIOnwai41z provide credentials, in this example a generated token
Date/Time Stamp Wen Sep, 18 07:49 BST 2019 Date and time for request or response message

REST Payloads

“The body of the request may contain a Payload that carries data to or from the service”.

Two formats are most common for the REST framework are:

JavaScript Object Notation (JSON). A text based standard designed to be human readable.

Example of JSON object:

{
  "iface type": "GigabitEthernet",
  "iface number": "2/0/12"
}

And the Extensible Markup Language(XML). Designed to store and transport data.

Example of an XML snippet:

<interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <interface>
        <name>GigabitEthernet1</name>
        <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
        <enabled>true</enabled>
        <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">
            <address>
                <ip>198.18.133.212</ip>
                <netmask>255.255.192.0</netmask>
            </address>
        </ipv4>
        <ipv6 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip"/>
    </interface>
    ...
</interfaces>

Note: You can find out what the REST payload format is by looking at the “Content-Type REST header”