Building Self Documenting HTTP APIs with CQRS

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





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 ChangesResource Model != Data Model





Breaking ChangesUnable to change endpoint routes

Breaking ChangesUnable to change endpoint routes





Ability to create an evolving Web API

EvolutionNot versioning…





ContractsData Transfer Objects

DB Entity JSON


DB

Entity

Entity

Resource JSON


DB

Entity

Entity

Resource Representation





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



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

Building Self Documenting HTTP APIs with CQRS

Technology