• image—image/png,image/jpeg,image/gif
• audio—audio/wav,audio/mpeg
• video—video/mp4,video/ogg
• application—application/json,application/pdf,application/xml,application/octet-stream

For example, a client accessing a resource withid23 in anarticlesresource on a server might send a GET request like this:

GET /articles/23
Accept: text/html, application/xhtml

TheAcceptheader field in this case is saying that the client will accept the content intext/htmlorapplication/xhtml.

Requests must contain a path to a resource that the operation should be performed on. In RESTful APIs, paths should be designed to help the client know what is going on.

Conventionally, the first part of the path should be the plural form of the resource. This keeps nested paths simple to read and easy to understand.

A path likefashionboutique.com/customers/223/orders/12is clear in what it points to, even if you’ve never seen this specific path before, because it is hierarchical and descriptive. We can see that we are accessing the order withid12 for the customer withid223.

Paths should contain the information necessary to locate a resource with the degree of specificity needed. When referring to a list or collection of resources, it is not always necessary to add anid. For example, a POST request to thefashionboutique.com/customerspath would not need an extra identifier, as the server will generate anidfor the new object.

If we are trying to access a single resource, we would need to append anidto the path. For example:GET fashionboutique.com/customers/:id— retrieves the item in thecustomersresource with theidspecified.DELETE fashionboutique.com/customers/:id— deletes the item in thecustomersresource with theidspecified.

Sending Responses

In cases where the server is sending a data payload to the client, the server must include acontent-typein the header of the response. Thiscontent-typeheader field alerts the client to the type of data it is sending in the response body. These content types are MIME Types, just as they are in theacceptfield of the request header. Thecontent-typethat the server sends back in the response should be one of the options that the client specified in theacceptfield of the request.

For example, when a client is accessing a resource withid23 in anarticlesresource with this GET Request:

GET /articles/23 HTTP/1.1
Accept: text/html, application/xhtml

The server might send back the content with the response header:

HTTP/1.1 200 (OK)
Content-Type: text/html

This would signify that the content requested is being returned in the response body with acontent-typeoftext/html, which the client said it would be able to accept.

Responses from the server contain status codes to alert the client to information about the success of the operation. As a developer, you do not need to know every status code (there aremanyof them), but you should know the most common ones and how they are used:

For each HTTP verb, there are expected status codes a server should return upon success:

• GET — return 200 (OK)
• POST — return 201 (CREATED)
• PUT — return 200 (OK)
• DELETE — return 204 (NO CONTENT) If the operation fails, return the most specific status code possible corresponding to the problem that was encountered.

Let’s say we have an application that allows you to view, create, edit, and delete customers and orders for a small clothing store hosted atfashionboutique.com. We could create an HTTP API that allows a client to perform these functions:

If we wanted to view all customers, the request would look like this:

GET http://fashionboutique.com/customers
Accept: application/json

A possible response header would look like:

Status Code: 200 (OK)
Content-type: application/json

followed by thecustomersdata requested inapplication/jsonformat.

Create a new customer by posting the data:

POST http://fashionboutique.com/customers
Body:
{
  "customer”: {
    "name” = "Scylla Buss”,
    "email” = "scylla.buss@codecademy.org”
  }
}

The server then generates anidfor that object and returns it back to the client, with a header like:

201 (CREATED)
Content-type: application/json

To view a single customer weGETit by specifying that customer’s id:

GET http://fashionboutique.com/customers/123
Accept: application/json

followed by the data for thecustomerresource withid23 inapplication/jsonformat.

We can update that customer byPUTting the new data:

PUT http://fashionboutique.com/customers/123
Body:
{
  "customer”: {
    "name” = "Scylla Buss”,
    "email” = "scyllabuss1@codecademy.com”
  }
}

A possible response header would haveStatus Code: 200 (OK), to notify the client that the item withid123 has been modified.

We can alsoDELETEthat customer by specifying itsid:

DELETE http://fashionboutique.com/customers/123

The response would have a header containingStatus Code: 204 (NO CONTENT), notifying the client that the item withid123 has been deleted, and nothing in the body.

Practice with REST

Let’s imagine we are building a photo-collection site. We want to make an API to keep track of users, venues, and photos of those venues. This site has anindex.htmland astyle.css. Each user has a username and a password. Each photo has a venue and an owner (i.e. the user who took the picture). Each venue has a name and street address. Can you design a REST system that would accommodate:

• storing users, photos, and venues
• accessing venues and accessing certain photos of a certain venue

Start by writing out:

• what kinds of requests we would want to make
• what responses the server should return
• what thecontent-typeof each response should be

Possible Solution - Models

{
  "user”: {
    "id": <Integer>,
    "username”: <String>,
    "password”:  <String>
  }
}

{
  "photo”: {
    "id": <Integer>,
    "venue_id”: <Integer>,
    "author_id”: <Integer>
  }
}

{
  "venue”: {
    "id": <Integer>,
    "name”: <String>,
    "address”: <String>
  }
}

Possible Solution - Requests/Responses

Request-GET /index.htmlAccept:text/htmlResponse- 200 (OK) Content-type:text/html

Request-GET /style.cssAccept:text/cssResponse- 200 (OK) Content-type:text/css

Request-GET /venuesAccept:application/jsonResponse- 200 (OK) Content-type:application/json

Request-GET /venues/:idAccept:application/jsonResponse- 200 (OK) Content-type:application/json

Request-GET /venues/:id/photos/:idAccept:application/jsonResponse- 200 (OK) Content-type:image/png

Request-POST /usersResponse- 201 (CREATED) Content-type:application/json

Request-POST /venuesResponse- 201 (CREATED) Content-type:application/json

Request-POST /venues/:id/photosResponse- 201 (CREATED) Content-type:application/json

Request-PUT /users/:idResponse- 200 (OK)

Request-PUT /venues/:idResponse- 200 (OK)

Request-PUT /venues/:id/photos/:idResponse- 200 (OK)

Request-DELETE /venues/:idResponse- 204 (NO CONTENT)

Request-DELETE /venues/:id/photos/:idResponse- 204 (NO CONTENT)

'The Codecademy Team, composed of experienced educators and tech experts, is dedicated to making tech skills accessible to all. We empower learners worldwide with expert-reviewed content that develops and enhances the technical skills needed to advance and succeed in their careers.'