Posted on

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

Posted on 7 Comments

Who Makes More Money? Technical Writers with Language or IT Skills?

money

Kai raised an interesting point about which skill (writing or technical) takes longer to master.

Knowing how to structure and present information to users? Or knowing how to use a product or application? That got me thinking. If you want to make money as a technical writer, which area should you focus on?

Sharpen your writing skills or deepen your technical knowledge, for example, learning how to document an API?

Which Technical Writers Makes The Most Money

I think there is more money if you have deep technical knowledge rather than strong writing skills.

Kai’s point is, “…it’s always been easier and faster to learn a product/app. So knowing about structuring and presenting information has been the more valuable skill in a writer – and the rarer one, too, that’s much harder to learn from colleagues!

So I agree with David: “… it’s easier for a good non-technical writer with an interest in technology to become a good technical writer, than it is for a good engineer to become one.”

… and with Ivan, that writers can make up deficiencies with interest: “… if someone has an interest in sharing how the technology works, then they will go the extra mile…”

I think the real issue is this:  Which skill takes longer to master?

I have to admit, that’s a very good way of looking at it. I hadn’t actually thought of it in those terms.

  • My take is that it’s easier to develop language/writing skills… or at least to develop them to a level where you can perform your duties as a technical writer.
  • With technology it’s more complex as (at least for me) I’m always learning. Even in areas where I have considerable knowledge, I still find that I’m learning and finding better ways of doing things.
  • When I started out my writing skills were rather ‘unsophisticated’ and that’s being kind. But, I knew how to program (Cobol, C, Fortran) and landed some nice contracts as a results. Writers with much better qualifications weren’t even considered.

I think there is more money if you have deep technical knowledge rather than strong writing skills.

What do you think?

Posted on 8 Comments

How To Write Technical Documentation For APIs

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?


APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API