cqrs api
TRANSCRIPT
● The town is a home to people, places and things. These are the nouns in your API
● Nouns are also called resources or entities.● The nouns are represented in your API by the URL.● Like things inside of your town, you can do thing with
your resources.● You tell your nouns to do things via verbs. ● The HTTP spec come with built in verbs, among these
are GET, PUT, POST, and DELETE● These verbs are great for CRUD functionality.
Your API is Like a Town
HTTP verb Resource URL Explanation
POST Creates a street
GET Gets all the streets in the town
GET Gets the street with the ID of 11
PUT Updates the street with the ID of 11
DELETE Deletes the street with the ID of 11
C
R
UD
Some Good Ideas to Follow:1. Use plural nouns2. Nest resources!
3. Handle errors with a standardized response body4. Use the standard HTTP verbs5. Use appropriate HTTP headers6. Use appropriate HTTP response codes
Read The Spec
Idempotent/Safe Methods
Idempotent methods can be applied over and over again and always have the same effect on the resource
Safe methods do not have any modifying effect on the resource
Idempotent/Safe MethodsMethod Idempotent SafeGET YES YES
POST NO NO
PUT YES NO
DELETE YES NO
PATCH NO NO
HEAD YES YES
OPTIONS YES YES
POST v PUT v PATCH
● POST is used to create an entity● PUT is used to update an entity where you
must send the entire representation of the entity as you wish for it to be stored
● PATCH is used to update an entity where you send only the fields that need updated
Client
Application Server
Client uses HTTP POST, GET, PUT and DELETEVerbs to CREATE, READ, UPDATE and DELETE
Create a Street
Server returns “201 created” status and a JSON representation of the newly created street, as well a link to the street
Update a Street
Server returns “200 OK” status and aJSON representation of the street,
NOTE: Most implementations of the PUT verb require the entire representation of the entity. See HTTP PATCH verb for updating with a partial representation of the entity.
Delete a Street
Server returns a ‘204 No Content’ status and should not have aresponse body. Any further GET requests to /api/streets/30 should return a ‘404 Not Found’ status
Awesome!● We can create some really awesome APIs
where we can create, read, update, and delete entities in a standard way.
● These standards have lead to some very powerful libraries that can help you create and consume CRUD APIs
Where is the Business Logic?Client
Application Server
Client uses HTTP POST, GET, PUT and DELETEVerbs to CREATE, READ, UPDATE and DELETE
● Sometime this is what we want● When we create APIs we don’t always know the specific
use case● We just want to expose the data
Business Logic on The Client Side?
● A CRUD API is a really good way to expose meaningful data in a flexible way
● You make few assumptions on how the data will be displayed or used
● Fosters innovation and allows for really interesting clients
Really? Client Side?
● Stopping at CRUD functionality limits what your API can actually do
● Complex business problems should not rely on client side implementations
● Only implementing CRUD functionality can lead to an API that doesn't know what it does, it only knows about the data it stores
Wait, This SUCKS!
How do you go beyond simply creating, reading, updating, and deleting things?● How do you repave a street?● Condemn a house?● Hospitalize a person?
Command API
Take a resources, add a command (verb) to the end, send data for that command in POST HTTP verb
○○○
Command or Resource?Command Resource
Verb Noun
You can only POST and sometimes GET never PUT or DELETE
All HTTP verbs are OK
Once a command has been submitted, it cannot be removed or updated (read only)
Most resources can be removed or updated
HTTP Verb
Command URL Explained
POST Sends the command to repave street 11
GET Meta data about repave command and street 11. Maybe the last time it was repaved, whether or not we are currently repaving
GET Meta data about the specific instance of the repave command
Example: Repave a street
Server response with ‘200 OK’ status, and meta data about the command:
In this example, the command is executed and completed within the lifecycle of the HTTP request.
Wait: That’s Not The Whole Story
We use a Commanding Pattern because we are performing an action on a resource. In the real word, these actions can take time.
Client
Application Server
Client sendsPOST command
Clients Checks Status URL until
complete, updating UI with progress
What About Querying?
● Sometimes a query request cannot be completed in a reasonable amount of time
● Sometimes you have to send a POST payload in order to send enough data for the server to process a query
● This is a special case of a command
Getting Results...If you try to hit the results link before the results are complete:● the server will return the search results in whatever
state is available● return a ‘203 Non-Authoritative Information’● a link to the status url● and a Retry-After headerUsing this pattern, you can expire content and return the 203 status code to tell the client to refresh the content
Getting Results...HTTP Request
Do we have the
resource?
203 With a Retry After Header And Status URL
200 OK
Has the data expired or still being created?
Check Status
Status
Is it done?
CQRS Martin FowlerCQRS stands for Command Query Responsibility Segregation. It's a pattern that I first heard described by Greg Young. At its heart is a simple notion that you can use a different model to update information than the model you use to read information. This simple notion leads to some profound consequences for the design of information systems.
http://martinfowler.com/bliki/CQRS.html
DDD WikipediaDomain-driven design (DDD) is an approach to software development for complex needs by connecting the implementation to an evolving model. The premise of domain-driven design is the following:1. Placing the project's primary focus on the core domain
and domain logic.2. Basing complex designs on a model of the domain.3. Initiating a creative collaboration between technical and
domain experts to iteratively refine a conceptual model that addresses particular domain problems.
http://en.wikipedia.org/wiki/Domain-driven_design
DDD and CQRS in My Own Words...● Domain Driven Design is a philosophy and methodology
in which your domain model should represent the business problems that your app is actually solving
● Command Query Responsibility Segregation is the strategy of separating commands from queries, as opposed to CRUD functionality which is represented in the same object. CQRS can help you follow the SOLID principle
DDD - Know Your Role!
● Talk to stakeholders and domain experts
● Strive for a ubiquitous language● Know the context in which your
API endpoints will be used● Use this knowledge to develop
your endpoints
CRUD API Commanding API
Create a Product
Update a Product
Mark Product as Active
Describe a Product
Order a Product
Markdown a Product
Review a products
Mark product as out of stock
CRUDY v Commandy
CQRS and CRUD Can CoexistPUT or PATCH is just an update command BUT:● Be very selective with what is allowed to be updated● It is not always appropriate to expose update
functionality for a particular object or property● If another command updates a property, updating that
property directly probably shouldn’t be allowedDELETE is a special use case command too