• 4 hours
  • Easy

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 4/2/20

Define a Typical Request and Response

Log in or subscribe for free to enjoy all this course has to offer!

Now that you know all about what a REST API is, what it's used for, and what the data looks like - you're ready to start working with APIs! 💪You already know that a REST API involves sending requests to the client and getting responses from the server. But what do these requests and responses look like?

The Structure of Requests

A Typical Request Structure
A typical request structure

Every request has a specific structure: 

HTTP Verb + URI + HTTP Version + Headers + Optional Message Body

It can look different depending on the software or language you use. This is what a request looks like in an application called Postman, which we'll talk more about in the next section. 

A Request in Postman
A Request in Postman

Now let’s break each one of these down:

HTTP Verb
HTTP verb

HTTP verbs are different types of actions you can take with your request - the most common ones that you’ll see are GET, PUT, POST, and DELETE. We'll cover these all in more depth later.

The Full Request URL
The full request URL includes the domain name + resource path

A URI or resource path is how you identify resources. For example, if you want to see all the users on your website, the path would be:

/users

If you want to see a specific user ID, it would be something like:

users/:userId

The request URL is the full endpoint you are using for your request. It combines the domain name and resource path.

The HTTP version is just the version of HTTP that is being used. The most common one you'll see is  HTTP/1.1.

Headers in a Request
Headers in a request

A header enables you to pass along additional information about the message. For example:

  • What language is it?

  • What date are you sending it on?

  • What software is the person using?

  • What is your authentication key?

Headers are in a key-value pair, and there are many different types of options for them. For example: 

Date: Tue, 19 Jan 2019 18:15:41 GMT

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5)

A Message Body
A message body

Finally, a message body is optional in every request and is usually used when updating or creating data with your API. It contains the actual data (in JSON or XML) of the resource you trying to create or update. If you want to add or update a user, you would add the user details in the message body using JSON. You'll learn more about this in the coming chapters.

The Structure of Responses

A Response Structure
A typical response structure

A response message has a similar format:

HTTP Version + HTTP Response Code + Headers + Message Body

In Postman, you can see a response message that looks like this:

A Typical Response Message
A typical response message

The message body has the information you asked for in JSON or XML. The image above shows a successful response for a request to the GitHub API. If the request was unsuccessful, the message body could have an error message:

An Unsuccessful Request
An unsuccessful request

The HTTP response code helps the developer and/or client understand the status of the response.  Here are the requests in Postman:

A successful response code
A successful HTTP Status code
An unsuccessful HTTP Status Code
An unsuccessful HTTP status code

When a client sends a request like, “Hey, can you send me all the tweets for this user?” You can think of the response code as something like a traffic light 🚥 telling you:
GREEN ✅: “This request was successfully processed.” or
RED 🔴: “We could not find anything about this request!”

There are a lot of different response codes - one you are probably familiar with is 404 Not Found. You may have seen this on a few websites. For example, when you try to go to a page that doesn't exist, you'll see something like:

GitHub 404 Response Page
GitHub 404 response page

Another important response code to know is 200 OK - which means your request was successful, and your response is good to go! In general, the rule of thumb for HTTP response codes is:

  • 100+ ➡ Informational

  • 200+ ➡ Success

  • 300+ ➡ Redirection

  • 400+ ➡ Client error

  • 500+ ➡ Server error

In the next chapter, we’re going to start working with real APIs, so it’ll be important to know the general formats for requests and responses, as well as what it looks like when a response is successful or not!

Let's Recap!

  • Requests take the form of:

    HTTP Verb + URI + HTTP Version + Headers + Optional Message Body

  • HTTP verbs are possible types of actions to take when making a request.

  • Responses take the form:

    HTTP Response Code + HTTP Version + Headers + Message Body

  • HTTP response codes are a kind of traffic light 🚦with specific codes to let clients know whether a given request was processed successfully or not. 

Example of certificate of achievement
Example of certificate of achievement