How to Write RESTful APIs

The following example shows how to document an API. This example is taken from the Bing Ads Content API, which is a RESTful API.

b52-bomber

RESTful API Example – Get Single Item

This section describes the type of API and some details about the type of operations it performs.

The Bing Ads Content API is a RESTful API. Standard CRUD-style operations (Create, Read, Update and Delete) are performed by sending HTTP requests to specific URL.

Next, it describes the HTTP request. This is composed of the following:

1. Header containing authentication fields

2. Body containing the data to be acted upon

3. Endpoint where the request will be sent

4. Mandatory or optional query string parameters to be appended to the endpoint URL.

The next section describes the operations and their requirements.

Purpose of Get Single Item

Retrieves the specified item from the product feed.

Note the construction.

1. Start with a verb, in this instance. Retrieves.

2. Identify what is specified, for example, the item from the product feed.

HTTP Request

This is a sample GET request.

GET https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcProviderId}/products/{productUniqueId}

Get Result

request
GData
auth/frontend/provider_unknown
Unknown provider-id in URL: {bmcProviderId}.
Examine the different parts of the string and how it’s constructed.

https

content.api.bingads.microsoft.com/

shopping/

v9.1/

bmc/

{bmcProviderId}/

products/

{productUniqueId}

URI Elements

There are two elements in the URI.

1. bmcStoreId – Replace with your Bing Merchant Center Store Id.

2. itemUniqueId – The unique Id of the item being retrieved, updated, or deleted. This is the fully qualified Id for this item, such as online:US:Sku123.

Query String Parameters

The three items to document here are: Parameter Name, Description, and Value.

warnings

1. Parameter – Warnings

2. Description – Returns a list of non-fatal warnings inside of the <sc.warnings> in the response body.

3. Value – Warnings are off by default. Specify this parameter with no value to enable warnings.

dry-run

1. Parameter – dry-run

2. Description – Performs the requested operation in dry-run mode. The response will contain any applicable errors or warnings, but no live data will be modified.

3. Value – Dry-run mode is off by default. Specify this parameter with no value to enable dry-run mode.

Request Headers

Here we document the Element, Description, and Data Type, for example:

AuthenticationToken – The OAuth access token used to manage Bing Ads accounts linked to a Microsoft Account. All of the data types are string. String.

DeveloperToken – The client application’s developer access token. String.

Password – The Bing Ads user’s sign-in password. String.

UserName – The Bing Ads user’s sign-in user name. You may not set this element to a Microsoft account. String.

Request Body

In this example, we do not supply a request body with this method.

Response Headers

Here we identify the Header Element and provide a description.

WebRequestActivityId – Provides a unique Identifier for the current request to be used for support purposes.

Response Body

We identify the response body which contains the specified items in the product feed format.

HTTP Return

For HTTP Return, we identify the HTTP Response Code, its Name, and a brief description.

1. HTTP Response Code – 200 – OK – The operation succeeded.

2. HTTP Response Code – 404 – NOT FOUND – The specified item ID does not exist.

You can read more about the API here: https://msdn.microsoft.com/en-US/library/bing-ads-content-api-reference.aspx

Have you got these templates?