LIL - Designing RESTful APIs (Common design challenges (Authentication…
LIL - Designing RESTful APIs
Who needs your API?
Why good API design is important
What functionnalities to expose
How to expose them
Best ways to expose it
Testing & validation
Versioning & backwards compatibility
Some allowed feature
What the API makes easy
What the API does
What the user wants to do
How do we add an API
You have an existing app and you add an API afterwards
Fastest way to get something useful
Takes advantage of the existing code and systems
Application and architecture issues "leak through" into the API
No underlying app. Complete flexibility.
"API first" / "mobile first" mindset
New technologies & new architectures
Team knowledge upgrade possible
Replacing the system piece by piece.
Ideal for legacy systems as the application is always functional.
Challenging to have "multiple mindsets" in the system
hard to replicate behavior for a 1:1 conversion
Tips for modeling APIs
Don't worry about the tools.
Have a consistent process.
It doesn't count unless it's written down.
People/entities using the API
Who are they?
Are they internal or external?
Are they active or passive participants?
Steps of the API design
Step 1: identify participants
Step 2: identify activities
Step 3: break into steps
Step 4: create API definitions
Step 5: validate your API
What does your API look like?
DELETE (delete a resource)
PUT (update existing resource)
POST (create a new resource or change status/state of a resource)
Movies & actors
Characters in movies
One actor plays multiple characters
One character played by multiple actors
Designing an API based only on your data base schema is a bad approach
How does your API work?
A generally agreed upon set of principles and constraints
Differences btw SOAP & REST
Fixed process vs flexi
lots of docs
complex error handling
REST design constraints
Better network performance
For idempotent requests
If you connect to something using the IP address straight away, when the IP address changes (which can happen), you have an issue. In this situation you where dependent on the network configuration, instead you should have used a DNS.
FLEXIBILITY TO IMPROVE AS REQUIREMENTS CHANGE
Code on Demand
Identification of Resources
Manipulation of resources through these representation
Hypermedia as the engine of application state (HATEOAS)
Common design challenges
Authentication & Autorization
Also AuthN & AuthZ
Not the same!
who you are?
context (daytime, location, device, ...)
attempted actions (especially for MFA)
framework and programming language agnostic
easy to add to the header/URL
URL is convenient but the information is loggedeverywhere.
header is also an issue in case the key would be compromised
Create your own protocol
untested, unproven, supported by us
everyone needs training
reliable & well-established
open source & commercial options
hard to implement
via the URL
via Accept Header
Establishes the markup/notation (usually XML or JSON)
Can establish the mediatype (structure of the markup)
Can establish the version of the mediatype (and resource)
not lost if you copy/paste the URL
Header is 'proper' but URL is easier
Media type & processing content
Hypertext Application Language (HAL)
odd to have a separate 'link' section with additional info (equivalentto footnotes you'd never read)
Ion Hypermedia Type
relatively recent, so little resources but high potential
Collection + JSON
En gors: plein de types de format différents pour transmettre l'info (?)
The mechanism which allows different versions of the same document to exist at a single URL so the client-server can determine which version best fits their capabilities.
A way of storing and retrieving data so that future requests can retrieve it faster without performing an operation (calculation, network request, etc.) again.
Client makes a request
Server responds and creates an ETag based on the resource state.
Client makes a HEAD request (same request as before)
If data is unchanged, server returns the same ETag - complete.
If data is changed, server returns a new ETag.
If the ETag is changed, client makes the full request.
code snippet friendly
easy to update
satisfies the goals
satisfies the goals (snippet via plug-in)
satisfies the goals (snippet via plug-in & history via git)
Jekyll based (all the same benefits)
rapid config & deploy (5min)
text & code can be easily brought together (?)
make users live easier
de not build a library nobody needs (ex REACT lib no one uses)
do not tailor something to one user only