The following example shows how to document an API. This example is taken from the Bing Ads Content API, which is a RESTful API.
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 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