Battelfield REST, API Development from the trenches

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