Super simple introduction to REST-APIs (2nd version)
Download as PPTX, PDF0 likes18,671 views
This document is a comprehensive introduction to REST APIs, explaining REST as an HTTP design pattern that maps server resources to URLs for client manipulation using HTTP verbs. It outlines the basics of HTTP, REST principles, API design best practices, and authentication methods, emphasizing the importance of treating APIs as products. The document also provides guidance on endpoint structure, interface quality, and implementation strategies for effective REST API development.
![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](https://image.slidesharecdn.com/rest-cursus-170407101945-190114092807/85/Super-simple-introduction-to-REST-APIs-2nd-version-13-320.jpg)
Super simple introduction to REST-APIs (2nd version)
- 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
- 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.
- 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/[email protected] (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/[email protected] DELETE https://domain.com/v1/profiles/[email protected] GET https://domain.com/v1/profiles/[email protected] (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
- 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