# REST Scenarios at MidFirst

GET https://services.dev.mfbdigital.com/user

Response:

{
  "pageInfo": {
    "pageSize": 3,
    "pageNumber": 1,
    "numberOfPages": 241,
    "numberOfRecords": 722
  },
  "results": [
    {
      "id": 1,
      "firstName": "Frodo",
      "lastName": "Baggins",
      "email": "frodo.baggins@midfirst.com"
    },
    {
      "id": 2,
      "firstName": "Bilbo",
      "lastName": "Baggins",
      "email": "bilbo.baggins@midfirst.com"
    },
    {
      "id": 3,
      "firstName": "Meriadoc",
      "lastName": "Brandybuck",
      "email": "meriadoc.brandybuck@midfirst.com"
    }
  ]
}

In this scenario, a paginated response is returned. These record items located within the results attribute of the response actually include more information than is returned here. For the view that is rendering this list response, however, this is all the information that is needed.

In order to render a detail view of any individual item, an additional request is made to get a full representation of it. These details will be used to build a form in the UI for all of the data for that object. We wouldn’t want to return all of these details in the previous list call, since most of this data is not shown on the listing UI.

GET https://services.dev.mfbdigital.com/user/1

Response:

{
  "id": 1,
  "firstName": "Frodo",
  "lastName": "Baggins",
  "email": "frodo.baggins@midfirst.com",
  "phone": "405-867-5309",
  "extension": "2112",
  "status": "ACTIVE",
  "department": 7,
  "supervisor": 2,
  "created": "2021-05-15T12:55:46.654Z",
  "lastUpdated": "2023-07-24T17:57:48.245Z"
}

The response for an individual object contains all of the information needed to update that object. However, there are still other sub-resources that are associated with it.

Namely, preferences. Because preferences are not directly used to update a user item, they are not included in the response for a user detail and must be fetched separately as a sub-resource.

GET https://services.dev.mfbdigital.com/user/1/preference

Response:

[
  {
    "id": 1,
    "type": "SETTING_1",
    "enabled": true,
    "value": null
  },
  {
    "id": 2,
    "type": "SETTING_2",
    "enabled": false,
    "value": null
  },
  {
    "id": 3,
    "type": "SETTING_3",
    "enabled": null,
    "value": "1234"
  }
]

This pattern of nesting sub-resources of individual items can continue for as long as necessary. If an individual preference item had some other sub-resource attached to it, it should be fetched in this way:

GET https://services.dev.mfbdigital.com/user/1/preference/1/sub-resource

PUT requests should be the preferred method of updating an object when the full detail is present or available. When making a PUT request the full object must be sent, not just the properties that have been updated.

PUT https://services.dev.mfbdigital.com/user/1

Request:

{
  "id": 1,
  "firstName": "Frodo",
  "lastName": "Baggins",
  "email": "frodo.baggins@midfirst.com",
  "phone": "405-867-5309",
  "extension": "2112",
  "status": "SUSPENDED",
  "department": 7,
  "supervisor": 2,
  "created": "2021-05-15T12:55:46.654Z",
  "lastUpdated": "2023-07-24T17:57:48.245Z"
}

Response:

{
  "id": 1,
  "firstName": "Frodo",
  "lastName": "Baggins",
  "email": "frodo.baggins@midfirst.com",
  "phone": "405-867-5309",
  "extension": "2112",
  "status": "SUSPENDED",
  "department": 7,
  "supervisor": 2,
  "created": "2021-05-15T12:55:46.654Z",
  "lastUpdated": "2023-07-24T17:57:48.245Z"
}

In this example, the API makes the changes and always returns the full detail in the response.

PATCH requests should be used to update an object when the full detail for that object is not present.

PATCH https://services.dev.mfbdigital.com/user/1

Request:

{
  "lastName": "Bagginz"
}

Or:

{
  "status": "SUSPENDED"
}

In each case, the full object should be returned in the response.

It is also important to note that all of the details that need to be updated on the record could be passed at the same time. However, for these scenarios consider making a PUT request.

Deletion of a resource should be requested with a DELETE request on the URI.

DELETE http://api.com/item/123

Responses to these requests may include a representation of the resource before it was deleted or simply a 200 OK. If a delete request is received for a resource that no longer exists the API may respond with a 200 OK or a 404 Not Found depending on the API, but it is best to remain consistent across endpoints once this decision is made.