See also: https://hersengarage.nl/rest-api-design-as-a-craft-not-an-art-a3fd97ed3ef4 An API in an interface or client-server-contract and REST is an HTTP design pattern. A REST-API is the de facto standard in web interface. It maps server resources onto URLs and allows CRUD-like manipulations of those (Create-Read-Update-Delete). In this presentation we cover the basics of: - The HTTP protocol - The REST design pattern - The API

1. Super simple introduction to
REST-API’s
For programmers
By Patrick Savalle (http://patricksavalle.com), software architect

2. Summary
• REST is an HTTP design pattern
• REST-APIs map server resources onto URLs
• Clients can manipulate resources using HTTP-verbs

3. CONTENTS
1. HTTP-BASICS
2. REST-BASICS
3. API-BASICS

4. PART 1
HTTP BASICS

5. Part 1 - HTTP - URL
Every resource has an unique URL that consists
of several parts.

6. Part 1 – HTTP - PROTOCOL
HTTP is a plain text conversation between a
client and a server. The conversation is based on
actions performed on resources which are
addressed by URL’s.

7. Part 1 - HTTP - Request
Requests and responses can contain header-fields
and a body. Everything is plain text. Headers usually
contain metadata or indicate conversation
preferences whereas the body contains content.

8. Part 1 - HTTP – Status codes
Every response contains a status code.

9. PART 2
REST BASICS

10. There is REST, SOAP, GraphQl and other API-protocols possible on HTTP, why REST?
• Every tool that can handle HTTP, can handle REST natively. For instance gateways, web-
servers and browsers can effectively cache, route, verify, manipulate REST requests and
responses. In short: the whole web supports REST
• It is simple and elegant
• Even simple (embedded) servers can implement it
• Less diversity in technology, you already use HTTP in your stack
Part 2 - REST - Why?
REST is HTTP ‘done right’.
Created by the same designer.

11. Part 2 - REST – The API
VERB + URL = ENDPOINT.
All endpoints together form the API.

12. Part 1 - HTTP - Verbs
The actions that can be performed on a resource are
called ‘methods’ or ‘verbs’. Below the commonly used
verbs (there are many more).
POST – create and other non-idempotent operations
PUT – replace
PATCH – (partial) update
DELETE – delete
GET – read
TRACE – echo
HEAD – headers only
OPTIONS – CORS preflight
Idempotent = no additional effects when called more than once with the same input.
In math: f(f(x)) = f(x), e.g. abs(abs(-1)) = abs(-1) = 1

13. ACTION RESOURCE
<verb> https://<host>/<api_version>[/<resource_type>/<instance_id>]
GET https://animal.api/1/lions (returns collection)
GET https://animal.api/1/lions/4 (returns single lion)
POST https://animal.api/1/lions (create new element)
PUT https://animal.api/1/lions/4 (updates element)
PATCH https://animal.api/1/lions/4 (partial update)
DELETE https://animal.api/1/lions (deletes collection)
DELETE https://animal.api/1/lions/harry@lion.com (deletes element)
GET https://animal.api/1/zoo/33/cage/9/animal/1
GET https://animal.api/1/lions?start=100&count=50
GET https://animal.api/1/lions?id=100&id=103&id=107 (parameter-array)
Part 2 - REST – Endpoint structure
An endpoint has a very strict URL structure. This is key to ‘REST’.
Map your domain resources onto URLs and allow them to be
manipulated.
Note: like in datamodelling all resources are always PLURAL

14. Part 2 - REST – Done wrong
REST is not SOAP.
An URL is NOT a RPC-address or method,
it is an universal RESOURCE locator
Bad REST API (bad URL’s in general):
POST https://domain.com/updateProfile
POST https://domain.com/deleteProfile
POST https://domain.com/createProfile
Good REST API:
POST https://domain.com/v1/profiles
GET https://domain.com/v1/profiles
PUT https://domain.com/v1/profiles/piet@puk.com
DELETE https://domain.com/v1/profiles/piet@puk.com
GET https://domain.com/v1/profiles/piet@puk.com
(Note: this ‘standard’ set is called ‘The Collection Metaphore’)

15. AUTHENTICATION
• HTTP BASIC AUTH
Client sends user/password in Authenication header with each API-call.
Simple, safe, good choice for API-2-API
• BEARER TOKEN
Get a temporary access token from API, put in Authentication header,
simple, safe, good choice for WEB-2-API
• OAUTH2 flow
Industry standard. Flexible. Safe. Mostly
used when authentication is done by an
external application (IDP). Often in
combination with Bearer Token.
Part 2 - REST - Authentication

16. PART 3
API BASICS

17. Possible run-time clients of your API:
• Other API’s
• Web applications and web front ends (like Angular, React, JQuery web apps)
• Mobile app’s, desktop applications etc.
• Machines, bots, things
But not:
• Humans
 Design an API ‘outside-in’, as a product for a generic client. Not just as the library for
your specific front-end. Use scenario’s or use-cases.
Part 3 - API – Outside-in
Don’t build your API for a specific type of client.

18. • Base your REST-API on a (the) domain model
(you MUST have a domain model for your application, reverse engineer this if it is not
present)
• Every parent or whole in the model is on a root URL
• Every child or part in the model is in an URL relative to its parent or whole
• Use the Collection Metaphore, each resource has a standard set of endpoints
The relevant desing patterns are described here: https://hersengarage.nl/rest-api-design-
as-a-craft-not-an-art-a3fd97ed3ef4
Part 3 - API – Best practice

19. • Consistent (avoid surprises)
• Cohesive (only lists purposeful endpoints)
• Complete (has all necessary endpoints for its purpose)
• Minimal (only one way to do things)
• Encapsulating (hiding implementation details)
• Self-explaining
• Documented!
 Same for all interfaces: class-interfaces, package interface, APIs, etc.
Part 3 - API – Interface quality
Good interface design is crafmanship.

20. • The OpenAPI /Swagger file
• Support
• Functional documentation
• A dashboard to register apps / obtain an API-key (API-manager)
• Language stubs (Java, PHP, Python, etc.) on Github
• A homepage / productpage
• A revenue-model / pricing
• A launchparty
• Hackathons
Part 3 - API - Deliverables
An API is a product, treat it as such.

21. Part 3 - API – Swagger / OpenAPI
The OpenAPI or ‘Swagger’ definition
Industry-standard to specify a REST-API. For an example, see:
https://gist.github.com/patricksavalle/fac25ed914dc2e10f256fdba1af9e622
The Swagger definitions are here:
https://swagger.io
Use the editor at:
https://editor.swagger.io
Every API comes with a Swagger!

22. Part 3 - API - Stateless
A REST-server must be client-state agnostic!
To be flexible and scalable the server needs to be ignorant of client-state or
context. A REST-server does not store session data on behalf of the client.
Put another way: all necessary context MUST be in the request.

23. 90% of all REST-methods follow the same implementation logic:
Request 
1. Authentication
2. Authorisation
3. Input validation
4. Actual logic
5. Output filtering
 response
Part 3 - API - Implementation
REST-servers are conceptually extremely simple,
keep their implementation equally simple.
(No design patterns, no fancy pancy)

24. Some of the choices only you can make:
• Few methods / large responses vs. many methods / small responses
Considerations: web clients generally like large aggregated responses tailored to their page
structures. Other clients like smaller responses. Etc. There is also the underlying (logical) data
model and the ‘natural granularity’ of the problem-domain. In most cases: map the domain
model onto URL’s.
• Query parameters vs request headers (for instance the API-tokens)
In general non-functional data should be in headers. Headers are more easily inspected / used
by tools like webservers..
• Hypermedia communication (follow-up URL’s in responses, HATEOAS)
Problematic concept, very client dependent.
Most API’s don’t have this, why should yours?
Part 3 - API – Design choices
Good interface design is crafmanship.

25. • A REST client, e.g. the Chrome POSTMAN plugin (most IDE’s have one as an add-on)
• TELNET (the generic HTTP client)
• http://www.restapitutorial.com/resources.html
• https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
• http://jsonapi.org/
• https://swagger.io/
• How to build a high quality REST-API:
https://hersengarage.nl/rest-api-design-as-a-craft-not-an-art-a3fd97ed3ef4
Part 3 - API - Resources