Staying Up to Date with the News API in Python/

...

/

The Request and Response Structure

The Request and Response Structure

Let's look at the request and response structure of News API.

We'll cover the following...

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:

Message

Description

apiKeyDisabled

The API key has been disabled.

apiKeyExhausted

The API key has no more requests available.

apiKeyInvalid

The API key hasn't been entered correctly. Double check it and try again.

apiKeyMissing

The API key is missing from the request. Append it to the request either as a query parameter or in the header.

parameterInvalid

We've included a parameter in your request which is currently not supported. Check the message property for more details.

parametersMissing


Required parameters are missing from the request and it cannot be completed. Check the message property for more details.

rateLimited

We have been rate limited. Allow some time to pass before attempting the request again.

sourcesTooMany

We’ve requested too many sources in a single request. Try splitting the request into two smaller requests.

sourceDoesNotExist

We’ve requested a source that doesn’t exist.

unexpectedError

This message is populated for an unexpected error. We can try the request again shortly.