DOC-2862 :: Feature :: Migrate REST API from MJ Wiki to Harmony Refer…

…ence (#116)

docs/agreements/rest-api.md

@@ -0,0 +1,35 @@
+---
+title: REST API
+---
+
+Here is our agreement to communicate Frontend/Mobile and Backend Applications using a REST API.
+
+## HTTP Returning Codes
+
+Note: Examples with a typical product endpoint: `/product?id=#product-id#`, `/product?id=1234`.
+
+1. **404 Not Found** | Wrong url return 404. Ex. `/prodct?id=1234`.
+2. **204 No Content** | When the url exist but the resource not, return 204 with empty body. Ex `/product?id=99999` 
+   where `99999` is a not existing ID in the list of products.
+3. **400 Bad Request** | A request without params or unexpected params, return 400. Ex. `/product/`, `/product/null`.
+4. **200 OK** | Call with WHERE (filtering) that doesn't mach any model, return 200 with an empty array. Ex. `/product?
+   whereName=pepito`
+
+We decided this agreement for these reasons:
+
+1. Distinguish a real 404 error (wrong url) on Monitoring System.
+2. Distinguish a malformed 400 request on the frontend/app on Monitoring System.
+3. The meaning of HTTP 4XX codes in the standard RFC 7231 it's a "Client Error".
+
+## Request Params
+
+1. Use **always Query Params**. Ex. `/api/v1/get-slider?brandId=1&campaignId=1...`.
+2. **Except** when we are using a **sensitive** data on the Request, send as POST or Body JSON. Ex. passwords
+
+We decided this agreement for these reasons:
+
+1. Avoid urls as `/api/v1/brand/1234/campaign/1234/detail/1234/slider/1234`.
+2. Instead, we can use a better endpoint as `/api/v1/get-slider` + queryParams `{brandId, campaignId, detailId, sliderId}`.
+3. Avoid merge GET and POST params at same time.
+4. Avoid that each Model appear as unique URL in Monitoring System (ex. `/product/1` and `/product/2` are two transactions on New Relic). Thanks to this we can have easily aggregated stats or errors for each endpoint.
+5. We can configure a cache response for each endpoint.

src/sidebars.js

@@ -148,6 +148,13 @@ module.exports = {
       type: "category",
       label: "Other resources",
       items: [
+        {
+          type: "category",
+          label: "Agreements",
+          items: [
+            "agreements/rest-api",
+          ]
+        },
         {
           type: "category",
           label: "Libraries",