rest-template-example.md

Show User

Returns json data about a single user.

• URL

  /users/:id

• Method:

  GET

• URL Params

  Required:

  id=[integer]

• Data Params

  None

• Success Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "users",
    "id": "1"
  }]
}

• Error Response(s):

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/firstName" },
      "title":  "Invalid Attribute",
      "detail": "First name must contain at least three characters."
    }
  ]
}

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "403",
      "source": { "pointer": "/data/attributes/secretPowers" },
      "detail": "Editing secret powers is not authorized on Sundays."
    },
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/volume" },
      "detail": "Volume does not, in fact, go to 11."
    },
    {
      "status": "500",
      "source": { "pointer": "/data/attributes/reputation" },
      "title": "The backend responded with an error",
      "detail": "Reputation service not responding after three requests."
    }
  ]
}

• Sample Call:

curl --location --request GET "{{base-url}}/articles/1?=" \
--header "Authorization: {{token_type}} {{access_token}}"

rest-template.md

**Title**
----

  <_Additional information about your API call. Try to use verbs that match both request type (fetching vs modifying) and plurality (one vs multiple)._>

* **URL**

  <_The URL Structure (path only, no root url)_>

* **Method:**
  
  <_The request type_>

  `GET` | `POST` | `DELETE` | `PUT`
  
*  **URL Params**

   <_If URL params exist, specify them in accordance with name mentioned in URL section. Separate into optional and required. Document data constraints._> 

   **Required:**
 
   ```bash
   id=[integer]

Optional:

photo_id=[alphanumeric]

• Data Params

  <If making a post request, what should the body payload look like? URL Params rules apply here too.>

• Success Response:

  <What should the status code be on success and is there any returned data? This is useful when people need to to know what their callbacks should expect!>

GET /articles/1 HTTP/1.1

• Code:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1"
  }]
}

• Error Response:

  <Most endpoints will have many ways they can fail. From unauthorized access, to wrongful parameters etc. All of those should be listed here.>

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/firstName" },
      "title":  "Invalid Attribute",
      "detail": "First name must contain at least three characters."
    }
  ]
}

<When multiple errors occur in response to a single request, the server can simply add each error to the errors array:>

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "403",
      "source": { "pointer": "/data/attributes/secretPowers" },
      "detail": "Editing secret powers is not authorized on Sundays."
    },
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/volume" },
      "detail": "Volume does not, in fact, go to 11."
    },
    {
      "status": "500",
      "source": { "pointer": "/data/attributes/reputation" },
      "title": "The backend responded with an error",
      "detail": "Reputation service not responding after three requests."
    }
  ]
}

• Sample Call:

  <Just a sample call to your endpoint in a runnable format (i.e. a curl request) - this makes life easier and more predictable.>

  curl --location --request GET "{{base-url}}/articles/1?=" \
  --header "Authorization: {{token_type}} {{access_token}}"

• Notes:

  <This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.>