Benify API Guidelines

Introduction

What is an API?

The term “API” means “Application Programming Interface”, and is the interface an application offers to others in order to use the services of that application. It is often viewed as a contract of what the application is providing to its users. The term is very broad and has been in use since the dawn of computing (almost). Nowadays however, the term “API” has been somewhat redefined to mean: “Web APIs”, or “APIs using RESTful HTTP/JSON”.

See [Wikipedia_API] and [Wikipedia_Web_API] for more information.

Benify APIs General Principles

In designing APIs at Benify, we try to adhere to the following principles:

• A Benify API shall adhere to the principle of least astonishment

This is a good principle to follow. It also means that an API designer has to understand the use of the API.

• A Benify API shall be “REST-ish”

This means that a Benify API shall adhere to common, well-known REST principles, so we’re using verbs, status codes, etc as is “normal” in the REST world. However, we do not go to full HATEOAS, meaning that the specifications we are publishing are the documentation of how to call our APIs.

• A Benify API shall be easy to understand and use

If it is hard to understand an API, it will be misused, misinterpreted, or not used at all.

• A Benify API should behave as you are expecting

… given REST knowledge.

• A Benify API adheres to the collection – item paradigm

Most of our APIs exposes collections of items. There are, of course exceptions…

• A Benify API adheres to common standards

We are adhering to standards as far as possible. (RFCs, OAuth, ISO and so on)

• A Benify API error should be clear and easy to understand

We have defined an error object which all of our APIs use.

• “Bulk” is our way of sending more than one payload in one call

We are using a “bulk transfer” pattern for sending multiple items in one call. This is for efficiency. One “bulk transfer” should behave exactly as if one is doing a number of ordinary calls.