There are lots of misconceptions about REST APIs. People think REST is about HTTP, and is not. That developer UX is important, but it will soon be dead. Here we discuss our approach to REST over HTTP and the difficulties and special scenarios we have found and how we solved them.

1. Skyrocketing Web APIs
By making the right decisions
Daniel Cerecedo
@dcerecedo

2. Why REST over HTTP?Why REST over HTTP?
@dcerecedoByteflair

3. Why REST over HTTP?Why REST over HTTP?
@dcerecedoByteflair
The limits of my language mean the limits of my
world.
Everybody speaks HTTP

4. Developer UXDeveloper UX
@dcerecedoByteflair
HTTP is for browsers

5. Developer UXDeveloper UX
@dcerecedoByteflair
Developer in mind, not browsers

6. REST over HTTPREST over HTTP
@dcerecedoByteflair
Components
URIs
Verbs
StatusCode
Body
Headers

7. REST over HTTPREST over HTTP
@dcerecedoByteflair
Separate resource representation from
contextual data
Representation Body→
Contextualdata Headers→

8. REST over HTTPREST over HTTP
@dcerecedoByteflair
HTTP status code to inform client about the
result
2xx Ok→
Other Ko→
4xx Clienterror→
5xx Servererror→

9. REST over HTTPREST over HTTP
@dcerecedoByteflair
Use best matching HTTP Status codes
Add specific application error codes to error
responses

10. @dcerecedoByteflair
REST over HTTPREST over HTTP
Semantic of an API should be In the URI
...but
Everybody thinks Verbs+URIs fit better on HTTP

11. @dcerecedoByteflair
REST over HTTPREST over HTTP

12. HypermediaHypermedia
@dcerecedoByteflair

13. HypermediaHypermedia
@dcerecedoByteflair
Applications can be modeled as state
machines

14. @dcerecedoByteflair
HypermediaHypermedia

15. @dcerecedoByteflair
HypermediaHypermedia

16. @dcerecedoByteflair
HypermediaHypermedia
Model the problem domain
Identifydomainresources
Identifyresourcestatetransitions

17. @dcerecedoByteflair
HypermediaHypermedia
Domain resources
Vehicles
Users
Sessions
Resource state transitions
Createresources
Assignownertovehicle
Activatesessionwithdriver&vehicle
Deactivatesession

18. @dcerecedoByteflair
HypermediaHypermedia
Define resource representation formats
Mime Types
Define roles for each Hypermedia Control
Rel Types

19. @dcerecedoByteflair
HypermediaHypermedia
GET /
Headers
Link:
<https://api.domain.com/vehicles>; rel=”vehicles”:
<https://api.domain.com/users>; rel=”users”:
<https://api.domain.com/sessions>; rel=”sessions”
Body
...

20. @dcerecedoByteflair
HypermediaHypermedia
GET /vehicles
Headers
Link:
<https://api.domain.com/vehicles?page=1&size=20>;
rel=”next”
Body
[ {...}, {…}, ...] Control links

21. @dcerecedoByteflair
HypermediaHypermedia
GET /sessions/1374
Body
{ ….
“vehicle”:”https://api.domain.com/vehicles/1”,
“driver”:”https://api.domain.com/users/1”
}
These are also control links.
Use conventions to get full semantics!!

22. @dcerecedoByteflair
HypermediaHypermedia
GET /vehicles/1
Body
{ ….
“owner”:”https://api.domain.com/users/1”
}
Relation types specify the role of the link

23. @dcerecedoByteflair
HypermediaHypermedia
GET /sessions/1374
Body
{ ….
“vehicle”:”https://api.domain.com/vehicles/1”,
“driver”:”https://api.domain.com/persons/1”
}

24. @dcerecedoByteflair
HypermediaHypermedia
Let the client discover its resource access level
Options

25. @dcerecedoByteflair
HypermediaHypermedia
Conventions
RelTypes,MediaTypes,Methods,StatusCodes

26. @dcerecedoByteflair
HypermediaHypermedia
Think as if you had to write a client and
minimize the number of things you
have to know about the API beforehand

27. @dcerecedoByteflair
HypermediaHypermedia
A client and an API do
not get decopupled
magically

28. Dynamic viewsDynamic views
@dcerecedoByteflair

29. Dynamic viewsDynamic views
@dcerecedoByteflair
We need different data access needs
for the same resource depending on
the security context

30. Dynamic viewsDynamic views
@dcerecedoByteflair
AnyUserresourcecanbefullyviewedbyan
administrator
AloggedinusercanfullyviewhisUserresource
Otheruserscanonlyseehispublicdata
Scenario

31. Dynamic viewsDynamic views
@dcerecedoByteflair
/users/{id}
/owner/users/{id}
/admin/users/{id}
OneURIperrole
Scenario

32. Dynamic viewsDynamic views
@dcerecedoByteflair
/users/{id}
/owner/users/{id}
/admin/users/{id}
OneURIperrole
Scenario

33. Dynamic viewsDynamic views
@dcerecedoByteflair
Partitiontheresource
Givedifferentroleaccesstoeachpartition
Scenario
/users/{id}
/users/{id}/my-private-data
/users/{id}/data-about-me-only-the-admin-knows

34. Dynamic viewsDynamic views
@dcerecedoByteflair
OneURIperresource
Selectoneviewatruntimedependingonthesecurity
context
Scenario
/users/{id}

35. Dynamic viewsDynamic views
@dcerecedoByteflair
1.Createamechanismtodefineviews
2.Createamechanismtodefineapplicableviewstoa
resource
3.Createamechanismtodefinewhichviewtoapply

36. Dynamic viewsDynamic views
@dcerecedoByteflair
1

37. Dynamic viewsDynamic views
@dcerecedoByteflair
1

38. Dynamic viewsDynamic views
@dcerecedoByteflair
2

39. Dynamic viewsDynamic views
@dcerecedoByteflair
3

40. Updates & ConcurrencyUpdates & Concurrency
@dcerecedoByteflair

41. @dcerecedoByteflair
Twoclientsattempttoupdatethesameresource
concurrently
Representationisthestateoftheapplication
Iwanttoavoidthesecondrequesttoupdatearesource
fromaninconsistentrepresentation
Updates & ConcurrencyUpdates & Concurrency
Scenario

42. @dcerecedoByteflair
Compareincomingresourceandexistingresource...
Updates & ConcurrencyUpdates & Concurrency
Scenario

43. @dcerecedoByteflair
Compareincomingresourceandexistingresource...
Ifunequalreject...
Updates & ConcurrencyUpdates & Concurrency
Scenario

44. @dcerecedoByteflair
Compareincomingresourceandexistingresource...
Ifunequalreject...
Ifpossibleinformtheuserwhichfieldsviolatedthe
precondition
Updates & Concurrency
Scenario

45. @dcerecedoByteflair
Ifwehavedynamicviews,thenthesameresourcemay
havedifferentfieldsfordifferentsecuritycontexts
Updates & ConcurrencyUpdates & Concurrency

46. @dcerecedoByteflair
Whatifwedon'twantallfieldstobeupdatable?
Whatifweneedfinegrainedaccesscontroltofields?
Updates & ConcurrencyUpdates & Concurrency
Scenario

47. @dcerecedoByteflair
1.Weneedamechanismtoassociatesecurity
expresionstofields
2.Weneedamechanismtoevaluatesecurity
expresionsbeforechangingthevalueofafield
Updates & ConcurrencyUpdates & Concurrency

48. @dcerecedoByteflair
Updates & ConcurrencyUpdates & Concurrency
1

49. @dcerecedoByteflair
Updates & ConcurrencyUpdates & Concurrency
2

50. Async RequestsAsync Requests
@dcerecedoByteflair

51. Async RequestsAsync Requests
@dcerecedoByteflair
Howdowedealwithtransitionsthatareintrinsically
asynchronous?

52. Async RequestsAsync Requests
@dcerecedoByteflair
Howdoweidentifyintrinsicallyasynctransitions?
Therearestatetransitionsbeyondyourcontrol
Itdoesnotmakesensetoreturnaresourcebecausewe
don'tknowthestateoftheresourceafterinvokingthe
transition

53. Async RequestsAsync Requests
@dcerecedoByteflair
Trucksareregularlyreviewedandmarkedforrepairing
Scenario
Ok
Needs
Repair
Repaired
Awaiting

54. Async RequestsAsync Requests
@dcerecedoByteflair
Trucksareregularlyreviewedandmarkedforrepairing
Scenario
Ok
Needs
Repair
Repaired
Within my organizations control
Awaiting

55. Async RequestsAsync Requests
@dcerecedoByteflair
Trucksareregularlyreviewedandmarkedforrepairing
Scenario
Ok
Needs
Repair
Repaired
Within my organizations control
Awaiting
PUT/trucks/6/repair
202Accepted

56. Async RequestsAsync Requests
@dcerecedoByteflair
Trucksareregularlyreviewedandmarkedforrepairing
Scenario
Ok
Needs
Repair
Repaired
Within my organizations control
Awaiting
PUT/trucks/6/repair
202Accepted

57. Async RequestsAsync Requests
@dcerecedoByteflair
Howdowedealwithtaskintensivestatetransitions?

58. Async RequestsAsync Requests
@dcerecedoByteflair
Howdowedealwithtaskintensivestatetransitions?
Wemakethemasync

59. @dcerecedoByteflair
Flexibility & DecouplingFlexibility & Decoupling

60. @dcerecedoByteflair
Flexibility & DecouplingFlexibility & Decoupling
MediationRouter+MessageBroker

61. @dcerecedoByteflair
Flexibility & DecouplingFlexibility & Decoupling
Mail Template
From
To
Subject
Template name
Amazon
Mailchimp
Elastic Mail
Scenario

62. @dcerecedoByteflair
Flexibility & DecouplingFlexibility & Decoupling
Scenario

63. @dcerecedoByteflair
Flexibility & DecouplingFlexibility & Decoupling
Scenario

64. @dcerecedoByteflair
Speakinginsilver
i18ni18n

65. @dcerecedoByteflair
Speakinginsilver
i18ni18n
GET /i18n/es_ES
Body
{
“country” : “ES”,
“lang”: “es”,
“data” : { “key”: “localized message”, ….}
}
SinglePageApp

66. @dcerecedoByteflair
API SpecificationAPI Specification

67. @dcerecedoByteflair

68. Byteflair
SwaggerSwagger
APIAPI SpecificationSpecification
Swagger editor:
http://editor.swagger.io/
En local:
https://github.com/Byteflair/docker-swagger-editor
docker pull byteflair/swagger-editor
docker run -d -p <port>:9000 byteflair/swagger-editor

69. Byteflair
RAMLRAML
APIAPI SpecificationSpecification
API Designer:
http://api-portal.anypoint.mulesoft.com/raml/api-designer
Imagen Docker:
https://github.com/Byteflair/docker-raml-editor
docker pull byteflair/raml-editor
docker run -d -p <port>:9013 byteflair/raml-editor

70. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet

71. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet
Client&User
User
Client
Trusted Untrusted

72. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet
Client&User
User
Client
Resource Owner
Credentials
Trusted UntrustedMy trusted native app

73. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet
Client&User
User
Client Client Credentials
Resource Owner
Credentials
Trusted Untrusted
A server app or CLI

74. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet
Client&User
User
Client
Authorization Code
Client Credentials
Resource Owner
Credentials
Trusted Untrusted
Third party apps

75. @dcerecedoByteflair
Oauth 2 CheatsheetOauth 2 Cheatsheet
Client&User
User
Client
Authorization Code
Implicit
Client Credentials
Resource Owner
Credentials
Trusted Untrusted
My single page app

76. @dcerecedoByteflair
Packaging & MonetizingPackaging & Monetizing

77. @dcerecedoByteflair
HowtoofferdifferentproductsontopofthesameAPI?
PackagingPackaging

78. @dcerecedoByteflair
HowtoofferdifferentproductsontopofthesameAPI?
BUNDLING subsetsoffunctionality
PackagingPackaging

79. @dcerecedoByteflair
HowtoofferdifferentproductsontopofthesameAPI?
BUNDLING subsetsoffunctionality
THROTTLING request
PackagingPackaging

80. @dcerecedoByteflair
HowtoofferdifferentproductsontopofthesameAPI?
BUNDLING subsetsoffunctionality
THROTTLING request
PackagingPackaging
Needs a proxy and means of updating policies

81. @dcerecedoByteflair
MonetizingMonetizing

82. @dcerecedoByteflair
ToolsTools

83. ToolsTools
@dcerecedoByteflair

84. @dcerecedoByteflair
“Weapons should be adapted to
your personal qualities and be
one you can handle” Miyamoto Mushashi

85. @dcerecedoByteflair
Don'tbecomean
extremist

86. ?Daniel Cerecedo
@dcerecedo
Thanks Gracias