This document provides a comprehensive introduction to REST APIs, outlining the fundamental concepts of HTTP, REST, and API design. It details how REST utilizes HTTP protocols for communication between clients and servers, the structure and methods used in RESTful URLs, as well as authentication mechanisms. Additionally, it emphasizes the importance of good API design, user interactions, and treating APIs as products to enhance scalability and flexibility.

1. Super simple
introduction to
REST-API’s
For programmers
By Patrick Savalle, innovation architect Delta Lloyd NV.

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

4. PART 1
HTTP BASICS

5. REST is HTTP/1.1. It is the native protocol of the web. Advantages are:
• Every tool that can handle Web / HTTP, can handle REST as native
‘content’. For instance gateways, web-servers and browsers can effectively
cache, route, verify, manipulate REST requests or responses.
• In short the whole web supports REST
• It is simple and elegant
• Less diversity in technology, you already use HTTP
Part1:~ Http$ WHY REST?_
REST is HTTP. It is the same protocol.
Created by the same designer.

6. Part1:~ 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. Part1:~ Http$ URL_
Every resource has an unique URL that
consists of several parts.

8. Part1:~ Http$ VERBS_
The actions that can be performed on a resource
are called ‘methods’ or ‘verbs’. Below the most
used verbs (there are many more).
POST – create
PUT – update
DELETE – delete
GET – read
PATCH – partial update
TRACE – echo
HEAD – headers only

9. Part1:~ Http$ Request_
Requests and responses contain header-fields
and possibly ‘content’. Everything is plain text.
Headers usually contain metadata or indicate
conversation preferences.

10. AUTHENTICATION
Part1:~ Http$ JSON RESPONSE_

11. Part1:~ Http$ STATUS CODES_
Every response contains a status code.

12. PART 2
REST BASICS

13. Part2:~ Rest$ ENDPOINTS_
The REST protocol is based on ‘endpoints’, which are
operations on resources addressed by URL’s.
Endpoints can be bundled to form an API.

14. 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/harry@lion.com (returns single lion)
POST https://animal.api/1/lions (create new element)
PUT https://animal.api/1/lions/harry@lion.com (updates element)
PATCH https://animal.api/1/lions/harry@lion.com (partial update)
DELETE https://animal.api/1/lions (deletes collection)
DELETE https://animal.api/1/lions/harry@lion.com (deletes single element)
GET http://www.example.com/1/customers/33245/orders/8769/lineitems/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)
Part2:~ Rest$ ACTION + RESOURCE_
An endpoint has a very strict URL structure. This is key to
‘REST’. Map your functional application resources onto the
WWW and allow them to be manipulated.

15. Part2:~ Rest$ ANTI-PATTERNS_
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:
PUT https://domain.com/1/profiles/piet@puk.com
DELETE https://domain.com/1/profiles/piet@puk.com
POST https://domain.com/1/profiles
GET https://domain.com/1/profiles/piet@puk.com

16. AUTHENTICATION
• HTTP BASIC AUTH
Client sends user/password in special header with each API-call. Simple,
safe, good choice for API-2-API
• TOKEN AUTH
Get a temporary access token from API, use in API-calls in username part
of HTTP BACIS AUTH, simple, safe, good choice for WEB-2-API
• OAUTH2
Industry standard. Flexible. Safe.
Part2:~ Rest$ AUTHENTICATION_

17. Part2:~ Rest$ JAVA EXAMPLE_
HttpResponse<JsonNode> jsonResponse =
Unirest
.post("http://httpbin.org/post")
.header("accept", "application/json")
.queryString("apiKey", "123")
.field("parameter", "value")
.field("foo", "bar")
.asJson();

18. PART 3
API BASICS

19. Part3:~ Api$ RULE NUMBER ONE_
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. As far as the
REST-server is concerned every call is the first call.

20. Part3:~ Api$ Economy_
There is an API for that. REST-API’s are the
glue of the Internet of Things.

21. Possible clients of your API:
• Other API’s
• Web applications and web front ends (like AngularJS, ReactJS, JQuery web
apps)
• Mobile app’s, applications etc.
• Machines, bots
• Typically NOT humans or ‘end users’
API’s are the glue of the internet of things (IoT).
Part3:~ Api$ Users_
On the internet nobody knows you’re a machine.

22. • Coherent
• 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!
 Design an API ‘outside-in’, as a product for a generic client. Not just as
the library for your specific front-end.
 Consider adding the role ‘interface designer’ to the team.
Part3:~ Api$ Interface quality_
Good interface design is crafmanship.

23. • The API
• Endpoint documentation
• A dashboard to register apps / obtain an API-key
• Language stubs (Java, PHP, Python, etc.) on Github
• Registration on programmableweb and similar
• A homepage / productpage
• A revenue-model / pricing
• A launchparty
• Hackathons
Part3:~ Api$ deliverables_
An API is a product, treat it as such.

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 data model onto URL’s.
• URL parameters vs request headers (for instance the API-tokens)
Considerations: in general non-functional data should be in headers. Headers are more
easily inspected / used by tools like webservers, giving transport flexibility.
• Hypermedia communication (follow-up URL’s in responses, HATEOAS)
Problematic concept, very client dependent.
Most API’s don’t have this, why should yours?
Part3:~ Api$ Interface 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/
Part3:~ Api$ RESOURCES_