REST API
Kaushik Kishore
Introduction
- 9+ years of experience in
building different kind of
products.
- Worked at multiple start-
ups. Designed and
implemented REST API for
UI/admin/public facing
2
Agenda
Introduction
Why REST API?
Request and Response formats
Endpoints (Noun)
Collection (Plurals)
Status Codes
Endpoint Nesting(Show relationships)
Retrieving large record set – filter, sort & paging
Versioning (very important)
Documentation
PRESENTATION TITLE 3
Introduction
01 02 03
REST stands for Any API (Application Simply put, a REST API is a
Representational State Programming Interface) medium for two computers
Transfer. It is a software that follows the REST to communicate over HTTP
architectural style created design principle is said to (Hypertext Transfer
by Roy Fielding in 2000 to be RESTful. Protocol), in the same way
guide the design of clients and servers
architecture for the web. communicate.
Why
Key points
• Flexibility
• Data is not tied to resource
• Can return different data types
• Client-Server
• Stateless
• Cache
• Uniform interface
• Layered System
• Code on demand
HTTP Request
methods
• HTTP defines a set of request methods to indicate the
desired action to be performed for a given resource.
• GET - The GET method requests a representation of the
specified resource. Requests using GET should only retrieve
data.
• HEAD - The HEAD method asks for a response identical to
a GET request, but without the response body.
• POST - The POST method submits an entity to the specified
resource, often causing a change in state or side effects on
the server.
• PUT - The PUT method replaces all current representations
of the target resource with the request payload.
• DELETE - The DELETE method deletes the specified
resource.
PRESENTATION TITLE 6
Headers
• Headers are a way to
include additional
information in an HTTP
request or response. They
can be used for various
purposes, such as
authentication, content
negotiation, and caching.
7
Request Headers
PRESENTATION TITLE 8
Response Headers
9
HTTP Request
methods - GET
A GET request is used to retrieve
information from a server. The
request includes a URL that
specifies the location of the
resource being requested, as well
as any query parameters that are
needed to specify additional
details about the request.
10
HTTP Request
methods -POST
A POST request is used to submit
new information to a server, such
as creating a new resource or
updating an existing one.
11
HTTP Request
methods - PUT
An HTTP PUT request is used to
update an existing resource on the
server.
12
HTTP Request
methods - PATCH
An HTTP PATCH request is used to
partially update an existing
resource on the server.
13
HTTP Request
methods -
DELETE
An HTTP DELETE request is used to
DELETE a resource on the server.
14
• Use JSON(JavaScript object notation)
as request and response format.
• You can use XML also, but this is a
Request and hassle to encode and decode the data.
• You can use HTML also as request and
Response response format
formats • You need to set headers while invoking
the API
• Content-Type: application/json
15
Use Nouns
Instead of
• Rest supports multiple https verbs such as GET, POST, PUT, DELETE etc.
• Never use verbs in endpoints. Always use Nouns
• A bad example
Verbs in
• Get posts (GET)
https://mysite.com/getPosts
•Create Post (POST)
https://mysite.com/createPost
Endpoints • A good example
• Get post (GET)
•https://mysite.com/posts
• To create a post (POST)
•https://mysite.com/posts
16
Name • You can think of the data of your API as
Collections
a collection of different resources from
your consumers.
• if you have endpoints like -
with Plural •
https://mysite.com/post/123
it doesn’t tell the user that there could
Nouns •
be some other posts in the collection.
So, instead
of https://mysite.com/post/123 , it
should be https://mysite.com/posts/123 .
17
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
You should always use regular HTTP status codes in responses to
requests made to your API. This will help your users to know what
is going on – whether the request is successful, or if it fails, or
something else.
Use Status • 100-level (Informational) – server acknowledges a
request. This interim response indicates that the client should
continue the request or ignore the response if the request is
Codes in •
already finished.
200-level (Success) – server completed the request as
Error •
expected
300-level (Redirection) – client needs to perform further
Handling
actions to complete the request
• 400-level (Client error) – client sent an invalid request
• 500-level (Server error) – server failed to fulfill a valid
request due to an error with server
• Add messages along with the error codes
18
Popular error codes are
• 200 – OK - The request succeeded.
Use Status • 201 – Request created
Codes in •
•
202 – Request accepted (For later processing)
400 Bad Request – client sent an invalid request,
Error such as lacking required request body or
parameter
Handling • 401 Unauthorized – client failed to authenticate
with the server
• 403 Forbidden – client authenticated but does
not have permission to access the requested
resource
• 405 – Method not allowed
19
Popular error which you'll encounter
404 Not Found – the requested resource does not exist
Use Status 412 Precondition Failed – one or more conditions in the
request header fields evaluated to false
Codes in 422 Un processable entity – client sent an invalid request
429 Too many request – Reached rate limit
Error 500 Internal Server Error – a generic error occurred on the
server
Handling 503 Service unavailable - the requested service is
not available
504 Gateway timeout
505 HTTP version not supported
20
• Oftentimes, different endpoints can be
interlinked, so you should nest them so it's
easier to understand them.
Use Nesting • For example, in the case of a multi-user
blogging platform, different posts could be
on Endpoints written by different authors, so an endpoint
such as https://mysite.com/posts/author would
make a valid nesting in this case.
to Show • In the same vein, the posts might have their
Relationships individual comments, so to retrieve the
comments, an endpoint
like https://mysite.com/posts/postId/comments
would make sense.
21
Use Nesting
on Endpoints
to Show
Relationships
Use Nesting on
Endpoints to Show
Relationships
23
Use Filtering, Sorting, and
Pagination to Retrieve the
Data Requested
• Sometimes, an API's database can get
incredibly large. If this happens,
retrieving data from such a database
could be very slow.
• Filtering, sorting, and pagination are all
actions that can be performed on the
collection of a REST API. This lets it
only retrieve, sort, and arrange the
necessary data into pages so the server
doesn’t get too occupied with requests.
24
Pagination
25
Pagination
26
Pagination
27
Pagination
28
SSL stands for secure socket layer. It is crucial for security in REST
API design. This will secure your API and make it less vulnerable to
malicious attacks.
Use SSL for Other security measures you should take into consideration include
Security making the communication between server and client private and
ensuring that anyone consuming the API doesn’t get more than
what they request.
The clear difference between the URL of a REST API that runs over
SSL and the one which does not is the “s” in HTTP:
https://example.com/posts runs on SSL.
http://example.com/posts does not run on SSL.
29
REST API versioning is the practice of including a version identifier in the endpoint
URLs of an API, in order to ensure that clients continue to work with the correct
version of the API, even as changes are made to the backend.
Be Clear REST APIs should have different versions, so you don’t force clients (users) to
migrate to new versions. This might even break the application if you're not careful.
with One of the commonest versioning systems in web development is semantic
versioning.
Versioning An example of semantic versioning is 1.0.0, 2.1.2, and 3.3.4. The first number
represents the major version, the second number represents the minor version, and
the third represents the patch version.
Many RESTful APIs from tech giants and individuals usually comes like this:
https://example.com/v1/ for version 1
https://example.com/v2 for version 2
Facebook uses the semantic versioning while Spotify uses the v1 or v2 versioning.
30
Versioning
Backwards compatibility: Versioning allows
you to make changes to your API without
breaking existing clients that rely on it. Clients
can continue to use the version of the API that
Increased complexity: Versioning adds an
extra layer of complexity to your API and requires
they are compatible with, while newer clients
more effort to maintain and test.
can take advantage of the latest features and
improvements.
Clear indication of changes: By including a Potential for confusion: If not implemented
version identifier in the endpoint URLs, it is clear correctly, versioning can cause confusion for
to developers which version of the API they are developers, who may not be sure which version of
working with, and what changes they can expect the API they should be using, or how to migrate
from one version to the next. from one version to another.
Improved documentation: When an API is Increased development time: When making
changes to a versioned API, you will need to test
versioned, it is easier to provide accurate the changes against all versions of the API
documentation for each version, making it
that are currently in use, which can increase
simpler for developers to understand and use the development time.
API.
PRESENTATION TITLE 31
• When you make a REST API, you need to help clients
(consumers) learn and figure out how to use it correctly. The
best way to do this is by providing good documentation for the
API.
• One of the most common tools you can use for API
documentation is Swagger. And you can also use Postman, one
of the most common API testing tools in software
development, to document your APIs.
Provide • The documentation should contain:
• relevant endpoints of the API
Accurate API • example requests of the endpoints
Documentation • implementation in several programming
languages
• messages listed for different errors with their
status codes
32
Best practices for documentation
• Make it clear and concise: Make sure that the documentation is easy to
understand and well-organized. Use clear and simple language and provide examples of how
to use the API.
• Provide detailed information: Include information about the API's endpoints,
such as the URL, the HTTP method (GET, POST, etc.), the request and response format, and any
parameters or headers that are required.
• Use clear and consistent formatting: Use a consistent format throughout
the documentation, such as a table or list, to make it easy to find the information you need.
• Include error handling: Clearly document what errors the API might return and
Documentation •
how to handle them.
Provide sample code: Include sample code snippets in multiple programming
languages to show developers how to interact with the API.
• Include authentication details: Provide information on how to authenticate
with the API, such as the required headers or tokens, and any API keys or secrets required.
• Provide contact information: Provide a way for developers to contact the API's
maintainers with questions or to report bugs.
• Keep it up-to-date: Make sure to update the documentation whenever there are
changes to the API, such as new features or bug fixes.
• Test the API: Before publishing the API documentation, it's important to thoroughly
33
Summary
In this, you learned about the
several best practices to bear in
mind when you're building REST
APIs.
It is important to put these best
practices and conventions into
practice so you can build highly
functional applications that work
well, are secure, and ultimately
make the lives of your API
consumers easier
34
Thank you
Kaushik Kishore • Q&A
[email protected]
