The Request and Response Structure

Request structure

A request for News API consists of only two elements:

• The authorization element.
• The required endpoint.

The authorization element

The API key is used for authorization for News API users. We can include the API key in the GET request through either of the following strategies:

• By including it as a query parameter called apiKey.
• By including the API key in the HTTP header. The element’s name will be X-API-Key or Authorization.

Note: In this course, we’ll send the API key in the header as X-API-key.

The required endpoint

We can use one of these three endpoints:

• sources
• everything
• top-headlines

We’ll discuss these endpoints and their uses with different query parameters in the upcoming lessons.

The response structure

News API’s response differs based on whether the request is successful or not. Let’s cover them one by one.

For a successful request

The response for a successful sources endpoint request is different from the response of everything and top-headlines. These response structures are as follows:

For the sources endpoint

The response for a successful request for this endpoint contains two main elements:

• status: This is ok in this case.
• sources: This contains all the available sources.

For the everything and top-headlines endpoints

The response for a successful request contains three main elements:

• status: This is ok in this case.
• totalResults: This tells us the total number of articles we got in the response.
• articles: This contains all the news articles.

For an unsuccessful request

The response for a successful request is the same for all three endpoints. It contains three main elements:

• status: This is error in this case.
• code: This is a short code identifying the type of error returned.
• message: This contains a description of the error and its fix. Here are the possible options for these error messages: