APIs (Application

Programming
Interface)
Structure of APIs,
status codes, web
services, demo
 Introduction
In this chapter we will look at a very essential concept in programming, APIs.

Lots of companies have spent lots of resources and time creating wonderful
solutions (payment, weather, music recognition).

If we want to embed these solutions into our own applications, we have to use the
APIs they created.
 Introduction
By the end of this course, you’ll be able to:

• Know some types of web services that exist

• Describe how REST APIs are structured

• Know the use of the different HTTP methods

• Know the significance of the different status code classes.

• Have some knowledge of how to interact with APIs using Postman

01
APIS
 API
• APIs serve as the intermediary layer that allows different software systems to
communicate and interact with each other.

• They define methods and protocols though which various components of

software applications can interact.

• APIs can be public (accessible by anyone) or private/restricted.

• Payment APIs like CamPay permit developers to integrate payment (MoMo and
OM) functionality into their applications without having to rebuild these
payment systems.

• Some other popular APIs include: social media APIs (Facebook, WhatsApp,
 Web services
• Web services are specific types of APIs made to function via the web

• Types of web services:

• SOAP (Simple Object Access Protocol): a protocol based on XML, imposing a
strict set of rules for communication

• REST (Representational State Transfer): more flexible and are based on

simpler data formats (JSON) and communication protocol (HTTP)

• GraphQL: An amelioration of REST, permits the querying of endpoints. Uses

similar protocols and data formats.
 HTTP (Hypertext Transfer
• Protocol)
HTTP is a protocol used for transmitting hypermedia documents, such as HTML.
- It enables communication between clients (e.g., web browsers) and servers
over the internet.

• HTTP clients use different HTTP methods to request for resources from the
server
• GET: used to retrieve data from the server

• POST: submit data to be processed by the server, used for resource

creation

• PUT: Update/add a resource to the server

• DELETE: remove data from the server

• PATCH: apply partial modifications to a resource.

 HTTP (Hypertext Transfer
• Protocol)
When the servers have treated the client requests, they add status codes to
the response. The status codes have the following significance:
• 20X: Success
• 30X: Redirection
• 40X: Client Error
• 50X: Server Error

• Some common HTTP status codes

Status Name Description
Code
200 OK Request processed successfully.

201 Created Request successful, resource created

204 No Content Request processed successfully, no content was

returned
301 Moved Permanently The resource has been moved to another location
 • Some common HTTP status codes
Status Name Description
Code
302 Temporary Redirect Temporary redirection to another URL for maintenance
purposes usually
400 Bad Request Client erro such as invalid parameters or invalid data.

401 Unauthorized The request requires authentication

403 Forbidden The client does not have permission to access the
requested resource
404 Not Found Server cannot find the requested resource

405 Method Not Allowed The HTTP method used in the request is not supported
for the specified resource.
500 Internal Server Error Server encountered an unexpected condition,
preventing it from fulfilling the request.
503 Service Unavailable Server is unable to handle the request
 Data Formats - XML, JSON
XML JSON
• XML is a structured, hierarchical • JSON is a lightweight data format
data format used for exchanging used in RESTful APIs.
information between applications.
• It is more human-readable and
• Commonly used in SOAP-based efficient compared to XML.
APIs.
 REST API Creation Guidelines
• REST is an architectural style for modeling distributed systems as a set of
resources.

• Resources can be data, objects, or services that can be accessed by clients.

• Every resource is represented by a URI which uniquely identifies the resource.

• Also, REST APIs (based on HTTP) are built around the HTTP actions such as GET,
POST, PUT, DELETE, and PATCH.

• Organizing the APIs around resources

• Entities are often grouped into collections (for example, users, items,
orders, etc). Use plural nouns to represent collections.

• Sending an HTTP GET request to a collection resource (example: /orders)

returns a list of items in the collection. Whereas the URL “/orders/12345”
represents a path to order with id 12345.
 REST API Creation Guidelines
• Define operations in terms of HTTP methods
• Use the appropriate methods for the different actions to be performed on
the endpoint

• Avoiding chattiness: avoid making the user have to send multiple requests back
and forth. To do this, you can implement endpoints that can add multiple
resources at once, as well as those for bulk delete and bulk updates.

• Pass the correct error codes and descriptions to the clients.

• API documentation is a reference manual containing all the information to work

with the API (e.g.authentication/authorization, input/output payloads, headers
and parameters).
• Some API description formats include Swagger Open API specification and
RAML. Look into Stripe API specification to get a good example
 GraphQL
• GraphQL is an API query language that defines specifications of how a client
application should request data from a remote server.

• You can use GraphQL in your API calls without relying on the server-side
application to define the request.

• GraphQL vs REST
• They both allow you to create, update and delete data via API. APIs developed
with REST are known as RESTful APIs while those with GraphQL are GraphQL
APIs.

• Both are stateless, so the server does not save response history between
requests
 GraphQL
• GraphQL vs REST
• REST and GraphQL both design their data interchange around resources. Each
resource has its own unique identifier (URI) and a set of operations (HTTP
methods) that the client can perform on it.

• Both REST and GraphQL support similar data formats. JSON is the most popular
format but XML and HTML are sometimes used.

• They both work with any database and programming language, highly
interoperable with any application.
 GraphQL
• GraphQL vs REST (differences)
• Overfetching and underfetching: REST APIs always return a whole dataset.
GraphQL emerged as a query-based solution, queries can extract the exact data
in only one API request and response.

• Error handling: GraphQL is a strongly typed API architecture, due to the level of
detail in the schema, the system can automatically identify request errors and
provide useful error messages. REST APIs are weakly typed, and you must build
error handling into the surrounding code.
 GraphQL
• When to use GraphQL or REST
• They can be used interchangeably but some use cases are a better fit for one or
the other

• When to use GraphQL

• You have limited bandwidth, and you want to minimize the number of requests
and responses
• You have multiple data sources, and you want to combine them at one endpoint
• You have client requests that vary significantly, and you expect very different
responses
 GraphQL
• When to use GraphQL or REST
• When to use REST
• You have smaller applications with less complex data

• You have data and operations that all clients use similarly

• You have no requirements for complex data querying

• This article from Amazon Web Services goes into more detail into this.
 Example of an API
• A simple REST API for user management:
• Endpoint: https://api.example.com/users

• GET Request (retrieve all users)

• Response
Example of an API
 PRACTICAL:
Interacting with
a Payment API