What is an API?

• Stand for "Application Programming Interface"
   
• A set of protocols, routines and tools to build software
   
• Allows 2 or more applications to talk to each other

Examples

• Google Map
  • Used to embed Google Maps, works on mobile & desktop
• YouTube
  • Lets you integrate videos and functionalities to a website
• Twitter
  • Allows you to access core data and provides methods to interact with trends

What's the benefit

• (usually) developer friendly
   
• Easy accessible and understood broadly
   
• Often a protection layer for security

Overview

• Web
• SOAP
• RPC
  • XML
  • JSON
• REST

Web API

Provides an interface for (Web) applications that need to connect to each other via the Internet to communicate

SOAP

• "Simple Object Access Protocol"
   
• Requires a SOAP library on the end of the client
   
• Not strongly supported by languages
   
• All calls send through POST
   
• Can be stateless or stateful
   
• Most difficult to use for developers

RPC

• "Remote Procedure Calls"
   
• 2 types: XML-RPC & JSON-RPC
   
• Requires users to know procedure names
   
• Easy for developers to get started with
   
• Specific parameters and order

REST(ful)

• "Representational State Transfer"
   
• No library needed, typically uses HTTP
   
• Returns data without exposing methods
   
• Single resource for multiple actions
   
• Supports any content-type (mostly XML & JSON)

Questions

• What type of API?
• For who do you build the API?
• Who will use the API?
• What is the purpose of the API?
• Why should someone use the API?
• How will the API interact with existing services?
• How will developers interact with the API?
• How to maintain the API?
• How to document properly?

REST more in depth

• "REpresentational State Transfer"
• An architectural style for network based software
• Can take and return multiple content types
• Terminology:
  • Stateless
  • URL
  • Resource
  • Collection
  • Endpoint
  • Request
  • Responses

Stateless

• After every request the server forgets everything, you client remembers your state
   
• You introduce yourself every time over and over again

URL

• "Uniform Resource Locator"
   
• The path to locate a resource to perform actions (methods) on it

Resource

• An object (model) which has some associated data with it
  • employee
  • company
  • car
     
• Can have a set of methods (actions) to operate on it e.g
  • GET: requests data from the resource
  • POST: requests the server to create a resource
  • PUT: update resource or create the resource
  • DELETE: speaks for itself

Collection

• A group of resources
   
• Example:
  • 10x employee => employees
  • 2x company => companies
  • 5x car => cars

Endpoint

Should contain resources and the method should define the action to be performed on a resource

// Endpoints, collection without action

/employees
/companies
/cars


// Methods/action to get the complete list per endpoint

GET /employees
GET /companies
GET /cars


// Methods to access one instance of a resource

// Shows the detail of employee number 20
GET /employees/20

// Deletes car number 100
DELETE /cars/100 

// Deletes employee 3 from company 5
DELETE /companies/5/employees/3 

Request

• Helps deciding what the response will be
   
• Format request can be done through:
  • URL (2 options)
  • HTTP headers

// Requests using keys and values

/companies?search=Competa
/cars?order=desc&sort=brand


// Format request (not recommended!)

/companies?format=xml
/employees?format=json


// Format request to download (better!)

/companies.xml
/employees.json


// See next slide for requests with HTTP headers (recommended!)
Accept: application/json
Accept: application/xml

HTTP headers

• Makes transactions clear and explicit
   
• Gives you proper information back in order to give a better response
   
• Examples:
  • Accept
  • Accept-language
  • Cache-Control

Responses

• After a request, you send back a response:
  • data
  • HTTP headers
    • Content-type
    • Last-modified
    • Status

// 1xx: Informational 
101: Switching to a newer protocol if there is an advantage.


// 2xx: Success 
200 OK: 
Standard response for successful HTTP requests.

201 Created: 
Successful creation occurred (via either POST or PUT).

204 No Content: 
The server successfully processed the request, but is not returning any content.


// 3xx: Redirection
301 Moved Permanently: 
This and all future requests should be directed to the given URI.


// 4xx: Client error
400 Bad Request: 
The request cannot be fulfilled due to bad syntax

401 Unauthorized: 
Error code response for missing or invalid authentication token

403 Forbidden: 
Error code for user not authorized to perform the operation or the resource is unavailable for some reason

404 Not Found:
Used when the requested resource is not found


// 5xx: Server error
501 Internal Server Error:
The general catch-all error when the server-side throws an exception.

502 Bad Gateway: 
The server was acting as a gateway or proxy and received an invalid response from the upstream server.

REST in short:

• Programmatic interface to logic and a data model (similar as building a website)
   
• You have a URL and when you request that URL you get something back