As an integration developer I have worked with a lot of different APIs and developed some strong preferences. I understand that getting the application to work is the priority and APIs come after, but maybe in sharing this it will change some API somewhere and make an integrator’s life easier.

Documentation

-Lots of examples

-Use explicit headings and over explain, so users can jump to the section they’re interested in and find all the information they could ever need.

-Do not be bashful. Document the parts that do not work the way they should, or you want them to. Users are going to find them. It is better to find them in the documentation instead of through hours of experimentation.

-Bonus points for swagger.

JSON

Please use JSON. It is well supported in most languages and simple to produce and consume.

Key, Value Pairs

It is quick and easy to retrieve data from and put data into a json key, value pair structure. It is a lot more work to deal with arrays of objects where the field name is the value of one key and the field value is the value of another key.

Good:

Bad:

[{“field”: “status”,

“value”: “processing”}]

Consistency

This is most easily understood through an example. The other day I was running a query and then a create. The query returned the field name “id”, but the create returned “Id”. Since I was expecting the same formatting in both cases my code initially did not work as expected and I had to spend time identifying the inconsistency and writing more code to deal with it.

Custom Fields

I know they are different, but it is so wonderful when they are treated the same. It is so much simpler to have a normal key, value pair for a custom field instead of having to go looking for them in some sub object with a different format.

For the most part APIs are like functions. As a developer the same things that make it easy to use other people’s functions, or your own when revisiting code after a break, make for good APIs.