Home
Application Walkthrough
The sample application is a ficticious order entry / inventory management system web api.
This walkthrough will cover creating a customer, category, product, and placing an order on behalf of the new customer via the api. Further, you will ship an order and see how it affects inventory as well. Along the way, you will see the peasy-js validation rules engine in action and how you can use concurrency techniques within your middle tier.
In order to successfully follow along with this tutorial, please be sure to read [running the application] (https://github.com/peasy/peasy-js-samples#running-the-application).
This tutorial uses Postman to interact with the web api, however, you can choose to use whatever http communication tool that you are comfortable with.
To begin, let's query our current users:
You should notice that one customer is returned and that a status code of 200 is returned.
Let's create a new customer who we will eventually place an order on behalf of:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. Make note of the customer id that was assigned.
Now let's query for existing categories:
You should notice that two categories are returned and that a status code of 200 is returned.
Let's create a new category:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. Make note of the category id that was assigned.
Now let's query for existing products:
You should notice that two categories are returned and that a status code of 200 is returned.
Let's create a new product and intentionally post an empty request body:
Notice that the response code is 400 and that we receive an array containing errors about the required values that were not supplied. These validation rules are wired up in the CreateProductCommand exposed via the ProductService. You can learn more about business services here and more about commands here.
Also notice that the returned error objects contain association and message values. The association field is particularly helpful for UI consumption scenarios.
Now let's attempt to create a new product, supplying all of the required information:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. Make note of the product id that was assigned.
Finally, let's delete a product that is no longer needed:
Notice that a DELETE request was made and resulted with a status code of 204.
Now let's query for existing inventory items:
You should notice that inventory items are returned and that a status code of 200 is returned.
Make special note of the inventory item with the product id of 3. This inventory item was created on our behalf when we created the "Javascript: the good parts" product.
Now let's create a new order on behalf of our new customer:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. Make note of the order id that was assigned.
Now let's add an order item specifying our new product (Javascript: the good parts) to the order:
Notice that a POST request was made with the content type set as application/json. The OrderItemService has been wired up with business rules associated with the insert that ensures that the order item's amount == the product price * quantity. Therefore, because we specified an amount of 51, we received a 400 status code and a validation error in our response payload.
Let's correct our mistake and attempt to create the order item again:
Notice that the request resulted with a status code of 201. Make note of the order item id that was assigned.
Now let's submit the order item, which indicates that it is ready to be shipped:
Here a POST request was made with the content type set as application/json. This may be confusing, as what we are really doing is moving order item from a PENDING state to a SUBMITTED state. This move operation is really more of an RPC action, which goes against the grain of a RESTFul design. However, due to security reasons, it makes most sense to expose the submission action as a POST against a order item.
Now that we've posted the order item, let's go ahead and ship it:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. However, notice that the status is set to BACKORDERED. This is because we never updated the inventory quantity for the "Javascript: the good parts" product.
Let's do that now:
In this update, we set the inventory quantity of the "Javascript: the good parts" to 10. Notice that a PUT request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 200.
Now that the inventory has been updated, let's attempt to ship the item again:
Notice that a POST request was made with the content type set as application/json. Further, notice that the request resulted with a status code of 201. In the response payload, notice that the status now states SHIPPED.
Now that the item has shipped, that should have reduced our inventory count for the Javascript book to 8, as the order item specified a quantity of 2.
Let's verify this:
You should notice that the inventory item is returned and that a status code of 200 is returned, and that the quantity on hand amount is set to 8 (10 - 2). Also take note of the version number, which was updated from 2 to 3.
This application was developed with concurrency in mind, and follows the last-write-wins approach on a field level. That stated, this api allows updates to entities on the individual field level for the majority of the entities.
Let's take a look by querying for product id:
Now let's update the name field for the product:
