building self documenting http apis with cqrs
TRANSCRIPT
![Page 1: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/1.jpg)
Building Self Documenting HTTP APIs with CQRS
Derek Comartin@codeopinion
codeopinion.com
![Page 2: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/2.jpg)
Context
![Page 3: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/3.jpg)
![Page 4: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/4.jpg)
TechSPA + HTTP API
![Page 5: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/5.jpg)
HTTP APIASP.NET WebAPI
![Page 6: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/6.jpg)
HTTP APIASP.NET WebAPI+ Entity Framework+ OData
![Page 7: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/7.jpg)
ClientAngularJS
![Page 8: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/8.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 9: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/9.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 10: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/10.jpg)
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.
![Page 11: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/11.jpg)
OARObject as Resource
HTTP VERB SQL STATEMENT
GET SELECT
POST INSERT
PUT UPDATE
PATCH UPDATE
DELETE DELETE
![Page 12: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/12.jpg)
Breaking ChangesUnable to Change Internals
![Page 13: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/13.jpg)
Breaking ChangesUnable to Change Internals
![Page 14: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/14.jpg)
Breaking ChangesUnable to Change Internals
![Page 15: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/15.jpg)
Breaking ChangesResource Model != Data Model
![Page 16: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/16.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 17: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/17.jpg)
Breaking ChangesUnable to change endpoint routes
![Page 18: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/18.jpg)
Breaking ChangesUnable to change endpoint routes
![Page 19: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/19.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 20: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/20.jpg)
Ability to create an evolving Web API
![Page 21: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/21.jpg)
EvolutionNot versioning…
![Page 22: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/22.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 23: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/23.jpg)
ContractsData Transfer Objects
DB Entity JSON
![Page 24: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/24.jpg)
ContractsData Transfer Objects
DB
Entity
Entity
Resource JSON
![Page 25: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/25.jpg)
ContractsData Transfer Objects
DB
Entity
Entity
Resource Representation
![Page 26: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/26.jpg)
3 Major Pain PointsBreaking Changes & Versioning
Unable to change internals data structuresModels still evolving
Unable to change endpoint routesBoundaries still evolving
Documenting Endpoints & Payloads
![Page 27: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/27.jpg)
RESTWat?
![Page 28: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/28.jpg)
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
![Page 29: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/29.jpg)
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.
![Page 30: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/30.jpg)
HypermediaLinks
![Page 31: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/31.jpg)
HypermediaForms
![Page 32: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/32.jpg)
ResourcesState + Actions
DB
Entity
Entity
DTO
RepresentationState
Links
Forms
![Page 33: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/33.jpg)
HypermediaLinks
![Page 34: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/34.jpg)
HypermediaLinks
![Page 35: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/35.jpg)
HypermediaLinks
![Page 36: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/36.jpg)
HypermediaForms
![Page 37: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/37.jpg)
HypermediaForms
POST: /books/addContent-Type: application/x-www-form-urlencoded
book_title=The+Goal%3A+A+Process+of+Ongoing+Improvement&book_price=1.45
![Page 38: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/38.jpg)
HypermediaForms
![Page 39: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/39.jpg)
HypermediaEmbedded Resources
![Page 40: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/40.jpg)
HypermediaEmbedded Resources
![Page 41: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/41.jpg)
HypermediaEmbedded Resources
![Page 42: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/42.jpg)
Media TypesHypermedia
• HAL• Collection+JSON• Siren• JSON API• Hydra and JSON-LD
![Page 43: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/43.jpg)
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
![Page 44: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/44.jpg)
http://www.codeproject.com/Articles/555855/Introduction-to-CQRS
Not this…
![Page 45: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/45.jpg)
Controller
Command
Query
Database
CQRS
![Page 46: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/46.jpg)
CQRS
Command = ResourceQuery = Resource
![Page 47: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/47.jpg)
Controller
Command
PUTPOST
DELETE
Query
GETOPTIONS
HEAD
Database
ResourcesCQRS
![Page 48: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/48.jpg)
MVCViewModel = State + Queries + Commands
DB
Entity
Entity
Razor
HTMLViewModel
Links
Forms
![Page 49: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/49.jpg)
Query ResourcesReturn State + Actions
DB
Entity
Entity
Query
RepresentationState
Queries
Commands
![Page 50: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/50.jpg)
Command ResourcesMutate State
DB
Entity
Entity
Command(Resource)
![Page 51: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/51.jpg)
ResourcesGet + Post + Redirect Pattern
Get Books The Goal Add To Cart Get Cart The Goal
![Page 52: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/52.jpg)
GET /api/books
![Page 53: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/53.jpg)
GET /api/books/243
![Page 54: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/54.jpg)
Request:POST /api/books/243/addToCart
Response:HTTP 1.1 303 See OtherLocation: /api/cart
![Page 55: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/55.jpg)
GET /api/cart
![Page 56: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/56.jpg)
GET /api/books/243
![Page 57: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/57.jpg)
Opaque URILook for the “Rel”
![Page 58: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/58.jpg)
VersioningEvolve your API
![Page 59: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/59.jpg)
VersioningEvolve your API
![Page 60: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/60.jpg)
Hide/show functionality based on payload
“Dumb” Client responsible for view/display
Easy to Navigate API
Success!
![Page 61: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/61.jpg)
Trade-offsNotes
State Transition/Flow
Analytics before resource removal301 Moved Permanently
No client magic dust
SPA Deep Linking
![Page 62: Building Self Documenting HTTP APIs with CQRS](https://reader034.vdocuments.site/reader034/viewer/2022051507/58e60c8b1a28ab44778b5729/html5/thumbnails/62.jpg)
That’s it…Thanks!
Derek Comartin@codeopinion
codeopinion.com