Please enable JavaScript.
Coggle requires JavaScript to display documents.
LIL - Designing RESTful APIs (Common design challenges (Authentication…
LIL - Designing RESTful APIs
Who needs your API?
Why good API design is important
Process
What functionnalities to expose
How to expose them
Best ways to expose it
Testing & validation
Repeat
Challenges
Naming
Interaction definition
Versioning & backwards compatibility
Concept
Affordances
Some allowed feature
Guideline
Combine:
What the API makes easy
What the API does
What the user wants to do
How do we add an API
3 approaches
Bolt-On Strategy
What?
You have an existing app and you add an API afterwards
Benefits?
Fastest way to get something useful
Takes advantage of the existing code and systems
Drawbacks?
Application and architecture issues "leak through" into the API
Greenfield Strategy
What?
No underlying app. Complete flexibility.
Benefits?
"API first" / "mobile first" mindset
New technologies & new architectures
Team knowledge upgrade possible
Drawbacks?
Harder.
Facade Strategy
What?
Replacing the system piece by piece.
Benefits?
Ideal for legacy systems as the application is always functional.
Drawback?
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.
Identifying participants
What?
People/entities using the API
To define
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?
HTTP Verbs
GET
DELETE (delete a resource)
PUT (update existing resource)
POST (create a new resource or change status/state of a resource)
Relationships
Independent
Example
Movies & actors
Dependent
Example
Characters in movies
Associative
Example
One actor plays multiple characters
One character played by multiple actors
Warning
Designing an API based only on your data base schema is a bad approach
How does your API work?
Terminology
HTTP
What?
Protocol
XML
What?
Mark-up language
Characteristics
Standards
JSON
What?
Notation
Characteristics
Specifications
REST
What?
A generally agreed upon set of principles and constraints
Differences btw SOAP & REST
Fixed process vs flexi
lots of docs
detailed scenario's
complex error handling
REST design constraints
Client-Server Architecture
Stateless Architecture
Why?
Stability
Scalability
Reliability
Flexibility
Cacheable
Why?
Better network performance
When?
For idempotent requests
Layered System
Example
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.
Why?
caching
logging
FLEXIBILITY TO IMPROVE AS REQUIREMENTS CHANGE
Code on Demand
6.Uniform Interfaces
Identification of Resources
Manipulation of resources through these representation
Self-descriptive messages
Hypermedia as the engine of application state (HATEOAS)
Common design challenges
Authentication & Autorization
Also AuthN & AuthZ
WARNING
Not the same!
Factors
who you are?
membership
subscription level
context (daytime, location, device, ...)
attempted actions (especially for MFA)
How?
API keys
Advantages
framework and programming language agnostic
easy to add to the header/URL
Disadvantage
URL is convenient but the information is loggedeverywhere.
header is also an issue in case the key would be compromised
Create your own protocol
Advantages
none
Disadvantages
untested, unproven, supported by us
everyone needs training
no resources
OAuth 2.0
Advantages
reliable & well-established
massive ecosystem
open source & commercial options
Disadvantages
complicated
hard to implement
Versioning
How?
via the URL
via Accept Header
Accept Header
Content Negotiation
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)
URL
easy
not lost if you copy/paste the URL
Conclusion
Header is 'proper' but URL is easier
Media type & processing content
Choices
Hypertext Application Language (HAL)
verbose
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
Others
Siren
JSON-LD
JSONAPI
Mason
UBER
OData
Atom
Collection + JSON
Hypermedia
What?
En gors: plein de types de format différents pour transmettre l'info (?)
HTTP Headers
Content Negotiation
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.
Caching
What?
A way of storing and retrieving data so that future requests can retrieve it faster without performing an operation (calculation, network request, etc.) again.
How?
ETags
Steps
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.
Documentation
DON'T
use PDF
Goals
code snippet friendly
page history
easy to update
searchable
Options
Wikis
Confluence
satisfies the goals
MediaWiki
satisfies the goals (snippet via plug-in)
Jekyll
satisfies the goals (snippet via plug-in & history via git)
Slate
Jekyll based (all the same benefits)
rapid config & deploy (5min)
text & code can be easily brought together (?)
SDK
SPOIL
Succint
Purposeful
Open Source
Idiomatic
Logical
Goal
make users live easier
Tips
de not build a library nobody needs (ex REACT lib no one uses)
do not tailor something to one user only