battelfield rest, api development from the trenches
DESCRIPTION
In this presentation we discuss the decisions that brought us to API development and why we focus just on delivering solutions around this technology. We discuss the implications of organizational learning and defining a systematic approach to API development with the goal of being able to automate as much as we can of the software development process. Eventually, we discuss the implementation choices we have made to accommodate advanced REST API requirements and the need to extend existing tooling.TRANSCRIPT
Battlefield RESTAPI's from the trenches
Daniel Cerecedo@dcerecedo
AgendaStrategic DriversTactical Choices
LanguageFramework dilemmaTools
Down to the trenchesURIsRepresentationsHypermediaViewsUpdates & Concurrency
Next Steps@dcerecedoByteflair
Strategic Drivers
@dcerecedoByteflair
Strategic DriversAgility & Flexibility
Heraclitus
@dcerecedoByteflair
“There is nothing permanent but change”
Strategic DriversGrowth
@dcerecedoByteflair
Strategic Drivers
RESTful Web Services
@dcerecedoByteflair
Strategic Drivers
Service dependabilityTime to market
Quality
@dcerecedoByteflair
Strategic DriversPutting it all together
@dcerecedoByteflair
QualityDependability
SpeedCost
Strategic Drivers
Jack of all trades,Master of none
Achieving dependability
@dcerecedoByteflair
Strategic DriversClimb faster, deliver faster
@dcerecedoByteflair
Automate
Strategic DriversPutting it all together
@dcerecedoByteflair
Deve
lopme
nt Co
sts
# Projects Executed
Every time output is doubledcost per unit falls by 15%
“1.000 days to develop,
10.000 days to polish”
@dcerecedoByteflair
Miyamoto Mushashi
Tactical Choices
@dcerecedoByteflair
@dcerecedoByteflair
“Weapons should be adapted to your personal qualities and be
one you can handle”
Tactical Choices
Miyamoto Mushashi
Tactical ChoicesJava & Spring
@dcerecedoByteflair
Community, Availability & Quality of Libraries
Scalability & Deployability
Object Oriented & Type Safe
We are already good at it
Tactical Choices
@dcerecedoByteflair
Here, we do it the PHP way
Tactical Choices
@dcerecedoByteflair
SpeedFlexibility
The framework dilemma
Tactical Choices
@dcerecedoByteflair
Tools
Swagger
Postman
“It is deplorable to
die with weapons left in
their scabbards”
@dcerecedoByteflair
Miyamoto Mushashi
Down to the trenches
@dcerecedoByteflair
URIs
@dcerecedoByteflair
URIs
What is the resource?/collection/{id}
Default
@dcerecedoByteflair
URIs
What is the resource?/collection;id={id}
/collection;slug={slug}/collection/{id};field={fieldName}
Multiple Id's
@dcerecedoByteflair
URIs
B has unique ids within AB has universal unique ids
A B1 N
Nesting
@dcerecedoByteflair
URIs
What is the resource and context?/collection_a/{aid}/collection_b/{bid}
A B1 N
Nesting – Unique Id's within A
@dcerecedoByteflair
URIs
What is the resource and context?/collection_a/{aid}/collection_b/
/collection_a/{aid}/collection_b/{bid}/collection_b/{bid}
A B1 N
Nesting – Universal Unique Id's
@dcerecedoByteflair
URIs
Why provide context to universal id's?
Faster queries in NoSQL(nested docs)
{ }@dcerecedoByteflair
URIs
A BN N
Nesting – Universal Unique Id's
A C1 N B1 N
@dcerecedoByteflair
...and apply the same recipe
...normalize...
URIsNesting – A note on Users
@dcerecedoByteflair
/users/{uid}/collection_b/{bid}
For the connected user:/collection_b/{bid}
URIsCalculations
@dcerecedoByteflair
Create a ficticious resource
Representation
@dcerecedoByteflair
Representation
HTTP Status CodeHTTP Headers
HTTP Response Body
Overloading HTTP
@dcerecedoByteflair
Representation
HTTP Status Code
Success Error
Identifying Response Outcome
@dcerecedoByteflair
Representation
HTTP Status provides contextResponse Body provides detail
{“code”: 123,“message”: “ source of the problem”,“hint”: “give me ways to overcome this obstacle”
}
Error
@dcerecedoByteflair
Representation
{“error”: null,“data”: { …}
}
Error
{“error”: { … },“data”: null
}
NO
@dcerecedoByteflair
Representation
{“field_a”: “value”,“field_b”: value,
...}
Success
@dcerecedoByteflair
[{…},{…},
...]
Representation
{“size” : 7,“data”: [
{…},{…},...
]}
Error
NO
@dcerecedoByteflair
Representation
If there is no need to wrap responsesDon't do it
@dcerecedoByteflair
Representation
HTTP HeadersElements in the array
Any metadata about the current response
@dcerecedoByteflair
Metadata
Representation
@dcerecedoByteflair
Expansion and Projections
Don't be opinionated about the client
Representation
@dcerecedoByteflair
Views
Representation
@dcerecedoByteflair
Updates & Concurrency
Hypermedia
@dcerecedoByteflair
Hypermedia
@dcerecedoByteflair
SHOW METHE MONEY
Hypermedia
@dcerecedoByteflair
URI's are Id's
“id” : “5ef321”
“id” : { “_link”: “http://api.domain.com/collection/5ef321”
}
“id” : “http://api.domain.com/collection/5ef321”
Hypermedia
@dcerecedoByteflair
Referencing “author” : {
“_link”: “http://api.domain.com/users/5ef321” }
“messages” : [ { “_link”: “http://api.domain.com/picks/3976dh
}, {
“_link”: “http://api.domain.com/picks/3976dh }, ...]
Hypermedia
HTTP HeadersPagination links
Link to the created resource
@dcerecedoByteflair
Metadata
Moving On
@dcerecedoByteflair
@dcerecedoByteflair
“Be victorious today
over what you were
yesterday”Miyamoto Mushashi
?Daniel Cerecedo
@dcerecedo