building self documenting http apis with cqrs
TRANSCRIPT
Building Self Documenting HTTP APIs with CQRS
Derek Comartin@codeopinion
codeopinion.com
Context
TechSPA + HTTP API
HTTP APIASP.NET WebAPI
HTTP APIASP.NET WebAPI+ Entity Framework+ OData
ClientAngularJS
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
OARObject as Resource
Alex Moorehttp://mooreniemi.github.io/rest/apis/2016/11/08/oar-is-not-rest.html
1. A resource maps 1:1(-ish) to an object in your server’s application logic.
2.URIs and HTTP methods are given conventions mapping to CRUD operations.
OARObject as Resource
HTTP VERB SQL STATEMENT
GET SELECT
POST INSERT
PUT UPDATE
PATCH UPDATE
DELETE DELETE
Breaking ChangesUnable to Change Internals
Breaking ChangesUnable to Change Internals
Breaking ChangesUnable to Change Internals
Breaking ChangesResource Model != Data Model
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
Breaking ChangesUnable to change endpoint routes
Breaking ChangesUnable to change endpoint routes
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
Ability to create an evolving Web API
EvolutionNot versioning…
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
ContractsData Transfer Objects
DB Entity JSON
ContractsData Transfer Objects
DB
Entity
Entity
Resource JSON
ContractsData Transfer Objects
DB
Entity
Entity
Resource Representation
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
RESTWat?
HypertextREST APIs must be hypertext-driven
When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.
Roy T. Fieldinghttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
HypertextWhat can I do with a resource?
Hypertext is a text which contains links to other texts. The term was invented by Ted Nelson around 1965.
HypermediaLinks
HypermediaForms
ResourcesState + Actions
DB
Entity
Entity
DTO
RepresentationState
Links
Forms
HypermediaLinks
HypermediaLinks
HypermediaLinks
HypermediaForms
HypermediaForms
POST: /books/addContent-Type: application/x-www-form-urlencoded
book_title=The+Goal%3A+A+Process+of+Ongoing+Improvement&book_price=1.45
HypermediaForms
HypermediaEmbedded Resources
HypermediaEmbedded Resources
HypermediaEmbedded Resources
Media TypesHypermedia
• HAL• Collection+JSON• Siren• JSON API• Hydra and JSON-LD
CQRS is simply the creation of twoobjects where there was previously onlyone.The separation occurs based uponwhether the methods are a command ora query (the same definition that is usedby Meyer in Command and QuerySeparation, a command is any methodthat mutates state and a query is anymethod that returns a value).
– Greg Young
CQRS
http://www.codeproject.com/Articles/555855/Introduction-to-CQRS
Not this…
Controller
Command
Query
Database
CQRS
CQRS
Command = ResourceQuery = Resource
Controller
Command
PUTPOST
DELETE
Query
GETOPTIONS
HEAD
Database
ResourcesCQRS
MVCViewModel = State + Queries + Commands
DB
Entity
Entity
Razor
HTMLViewModel
Links
Forms
Query ResourcesReturn State + Actions
DB
Entity
Entity
Query
RepresentationState
Queries
Commands
Command ResourcesMutate State
DB
Entity
Entity
Command(Resource)
ResourcesGet + Post + Redirect Pattern
Get Books The Goal Add To Cart Get Cart The Goal
GET /api/books
GET /api/books/243
Request:POST /api/books/243/addToCart
Response:HTTP 1.1 303 See OtherLocation: /api/cart
GET /api/cart
GET /api/books/243
Opaque URILook for the “Rel”
VersioningEvolve your API
VersioningEvolve your API
Hide/show functionality based on payload
“Dumb” Client responsible for view/display
Easy to Navigate API
Success!
Trade-offsNotes
State Transition/Flow
Analytics before resource removal301 Moved Permanently
No client magic dust
SPA Deep Linking
That’s it…Thanks!
Derek Comartin@codeopinion
codeopinion.com