What is an API (Introduction to APIs)

Carrying on from my previous posts on SOA here and here I thought it may be useful to write a post on what an API is, giving some lower level information on my previous posts and an introduction to non-programmers (and junior programmers). We will be focusing on HTTP API’s (but will give a bried intro to non-http based API’s too)

Introduction to APIs – What is an API?

Much like a regular web site serves a document (eg html, css, we will get to javascript later) which gets rendered in a browser, an (http) API provides documents from various ‘endpoints’ (think urls, but in code).

Introduction to APIs – What does it do?

These endpoints can accept data, or can provide data (they can provide all the CRUD [create, read, update, delete] operations). These can be used by developers (and regular users) to search information, update records, and most importantly as part of an SOA they provide a service whihc can be combines with other services to create an application. Much like class methods can be called when writing code API’s can be used to provide functionality.

What types of API are available?

There are loads of different standards out there, as there are with most computer-science things.
WSDL, SOAP, UDDI, XML, HTTP, XSLT, REST, AJAX, RPC. The popular one for web about 10 years ago was SOAP/WSDL – you may still come across SOAP services, but the big one these day are RESTFUL services. Ajax is everywhere too, so you may want to dig into how that works (javascript code fires an asynchronous call to a service somewhere, gets data back and processes/renders it in a browser).

What protocols / services are they delivered over?

HTTP mostly, but also custom protocols, etc

What are the main document formats?

JSON and XML

What is a REST service?

REST (Representational State Transfer) is an architecture for a stateless web service.
Being stateless, it means that all information has to be passed to the server in the request. no information is saved between sessions on the server.
In REST, a set of URLs are defined, and along with the HTTP methods are used for fetching or sending data.
the different HTTP methods are: GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, OPTIONS and TRACE.

What does it look like?

Stripe has an awesome API (and great documentation)

Introduction to APIs – REST Requests:

looking at the methods available most of the calls look like this:

POST /v1/charges (create a new charge)
GET /v1/charges/:id (get details on a specific charge)
POST /v1/charges/:id (update an existing charge)
POST /v1/charges/:id/capture (capture a charge - their term for 'take the money')
GET /v1/charges (get details on all charges)

This pattern is then expanded to all of their services (customers, balances, refunds, etc)

Introduction to APIs – REST Responses:

You can see that their responses are in JSON

{
"id": "ch_1GgSDc2eZvKYlo2CsE64jXmO",
"object": "charge",
"customer": {
"id": "cu_1GgRxV2eZvKYlo2CTqeghAtv",
"object": "customer",
...
},
"invoice": {
"id": "in_1BjO2g2eZvKYlo2CZ1hP1oD9",
"object": "invoice",
"subscription": {
"id": "su_18NVZi2eZvKYlo2CvZXG1Cl5",
"object": "subscription",
...
},
...
},
...
}

Stripe have very detailed explanations of whats available for every service, and the data thats required to be sent (this information can come in very handy when testing, eg a service requires an int, but what happens when you send a srting or an object)

Introduction to APIs – REST/HTTP Error codes:

You can see that they use standard HTTP response codes to indicate error/success

200 – OK Everything worked as expected.
400 – Bad Request The request was unacceptable, often due to missing a required parameter.
401 – Unauthorized No valid API key provided.
402 – Request Failed The parameters were valid but the request failed.
403 – Forbidden The API key doesn’t have permissions to perform the request.
404 – Not Found The requested resource doesn’t exist.
409 – Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 – Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 – Server Errors Something went wrong on Stripe’s end. (These are rare.)

What is a soap service?

Requests

SOAP (Simple Object Access Protocol) is also an architecture for a web service. it uses XML as its docuemtn type. SOAP can operate over any protocol, its not tied in to HTTP (like REST) https://en.wikipedia.org/wiki/SOAP
What does it look like?
http://www.gcomputer.net/webservices/dilbert.asmx

POST /webservices/dilbert.asmx HTTP/1.1
Host: www.gcomputer.net
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://gcomputer.net/webservices/DailyDilbert"





dateTime

Introduction to API’s – SOAP Responses

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length





string

How to find APIs

Scan things. Read the developer documents (they will usually give the endpoints away). A lot of APIs use semantic versioning in their urls, for example:

www.example.com/api/v3/users

You can see such requests in the developer tools in firefox, chrome, etc
just ‘inspect element’ and select ‘Network’, and watch as requests are fired off as you click buttons or tabs.

Wireshark is also useful, and Burp too, for replaying requests. I’ll be doing another post on how to find APIs and how to debug/test them.

Frameworks used to build API’s

There are tons and tons of ways developers build an API. In modern development its usually API-first, and frontend services are built to consume those services. API’s can be written in any modern language:

Java, C++, .net, PHP, PYTHON, JAVASCRIPT [nodejs] etc.

I hope you enjoyed and/or learned from this Introduction to APIs post

sources:
https://en.wikipedia.org/wiki/Representational_state_transfer
https://en.wikipedia.org/wiki/SOAP