From 7e6351fa9b2b80a6c57a974de1fb0bb63a8640f7 Mon Sep 17 00:00:00 2001 From: mlemorvan Date: Fri, 14 Jan 2022 16:32:35 +0100 Subject: [PATCH 1/2] recipe: create with an already known id --- recipes/create-with-id-already-known.md | 46 +++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 recipes/create-with-id-already-known.md diff --git a/recipes/create-with-id-already-known.md b/recipes/create-with-id-already-known.md new file mode 100644 index 0000000..ff43e06 --- /dev/null +++ b/recipes/create-with-id-already-known.md @@ -0,0 +1,46 @@ +--- +description: How to create a resource when the id is already known? +complexity: 1 +--- + +# Create a resource with an already known id + +## Use-case + +In most cases, we use POST for creating a new resource. The request is made on the collection, and the server is responsible for generating the id of the new resource: +```bash +POST https://api.example.com/v1/orders HTTP/1.1 + +< 201 Created +< Location: https://api.example.com/v1/orders/42 +``` + +But sometimes, the id of the resource to create is already known by the client. + +This can happen when: +- The business object has been created first in another application, and we want to use the same id when synchronizing it with our API. + - e.g.: when a product is purchased, the PSP generates a Transaction id when the payment is complete. + Then we want to create a new `/transactions` resource on our Order API, using the id given by the PSP. +- The resource id is not randomly generated but has a business meaning, and can be chosen client-side + - e.g.: I want my products to be identified by their business identifier: EAN, UPC... + +## Recipe + +You should use `PUT` instead of `POST` for creating the resource, and give the id in the url. + +For example, to create a new `product` with id `761234567890`: +```bash +PUT https://api.example.com/v1/products/761234567890 HTTP/1.1 +{ + "label": "My new product" +} + +< 201 Created +``` + +The syntax is the same as for a complete update: `PUT` kind of perform an upsert on the resource. + +## Resources + +- [PUT definition in the HTTP RFC](https://datatracker.ietf.org/doc/html/rfc2616#section-9.6) +> If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. From c72240d0001e17fe97e84b0cffa85b6d65510b8a Mon Sep 17 00:00:00 2001 From: mlemorvan Date: Fri, 14 Jan 2022 17:25:22 +0100 Subject: [PATCH 2/2] revue de code --- recipes/create-with-id-already-known.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/recipes/create-with-id-already-known.md b/recipes/create-with-id-already-known.md index ff43e06..0969067 100644 --- a/recipes/create-with-id-already-known.md +++ b/recipes/create-with-id-already-known.md @@ -19,10 +19,10 @@ But sometimes, the id of the resource to create is already known by the client. This can happen when: - The business object has been created first in another application, and we want to use the same id when synchronizing it with our API. - - e.g.: when a product is purchased, the PSP generates a Transaction id when the payment is complete. + - e.g.: when a product is purchased, the Payment Provider generates a Transaction id when the payment is complete. Then we want to create a new `/transactions` resource on our Order API, using the id given by the PSP. - The resource id is not randomly generated but has a business meaning, and can be chosen client-side - - e.g.: I want my products to be identified by their business identifier: EAN, UPC... + - e.g.: I want my products to be identified by their business identifier: [EAN (European Article Numbering)](https://fr.wikipedia.org/wiki/Code-barres_EAN), [UPC (Universal Product Code)](https://fr.wikipedia.org/wiki/Code_universel_des_produits)... ## Recipe @@ -38,7 +38,9 @@ PUT https://api.example.com/v1/products/761234567890 HTTP/1.1 < 201 Created ``` -The syntax is the same as for a complete update: `PUT` kind of perform an upsert on the resource. +The syntax is the same as for a complete update: `PUT` kind of perform an upsert on the resource. + +In the case of a creation, the [201 Status Code](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/201) is expected. ## Resources