Top tips for building a terrible API

API codeIn building a range of Seamless connector plugins, we’ve worked with a number of APIs for different platforms. That experience has sometimes been an absolute validation of how the API ecosystems should work (shout out to Dynamics, Autotask and Freshdesk) and sometimes, well, sometimes just a big ol’ steaming pile of unmentionableness.

1. Make sure your documentation is inconsistent, poorly indexed and difficult to understand and also terribly written as well as hopefully inklude some typos

Documentation is a sign of a mature API. It signals that the API publisher has thought about who is going to use the API and what they will need to do with it. For this reason, it is important to have as much documentation as possible. Thud factor gives developers confidence.

Keeping the documentation up-to-date and consistent is the work of amateurs – for terrible APIs you want to make sure the documentation has never been reviewed or updated. It is also good if it mentions both future and deprecated features as if they are current.

Coupled with a massive volume of documentation, it is also helpful if the documentation is poorly writed and understanding can also be difficult. This means developers will likely read the documents three or four times, giving the chance for greater reflection and cementing understanding.

2. Data formatting consistency is for chickens

In a recent development we worked with an API which used US dates for one set of functions and epoch dates for another. This is a great example of terrible API development, and not only because the US date standard is ridiculous. In our case, this extended the development time by at least a day, largely because it was coupled with poor documentation and no supportive information online.

3. Use different data standards in different parts of your system

JSON is a standard. XML is a standard. Your contract developer’s own views on consistent naming which are not documented anywhere and were actually only applied in his first week are also a standard. Using them interchangeably poses the developer a good challenge. Why limit yourself?

4. Data structures are for weaklings

Change your data structure as often as possible. It is important to make the API consumer’s job as demanding as possible by ensuring that the data structure used to send data is different to that in which you take updates back. If you absolutely insist on sticking to a single standard, at least vary the way you implement it to keep developers on their toes.

5. Build a community of totally unhelpful online nonsense

Online communities are great for SEO. Some companies also use them to help developers achieve more, but really what you’re looking for is lots of online pages to give you gravitas in search results. If you want to take this up a level, you can employ community managers to respond to queries with answers that refer users back to unhelpful documentation. You want to be sure that any answer has enough of a tidbit to look credible, but not so much that it will help developers solve any particular problem. Ultimately, guess work makes the dream work.

6. Make accessing trials really really difficult

Developers love solving problems so you might as well get them troubleshooting right out of the gate. Making a simple registration/login is much too easy. Create a sense of challenge by making them register, click an emailed link to confirm, download a white paper, interpret jumbled up images, solve a sudoku puzzle and paste a 22 character alphanumeric code from a text message onto a form. Start as you intend to finish.

7. Error messaging is for sissies

Only the most expedient developers like error messages. What you want in a terrible API is either no error messaging (or, indeed, success messaging) and / or error messages with GUIDs which relate to nothing in particular. Developers love a good GUID (who doesn’t?), throw a few around they’ll be like putty in your hands.

Recommended Posts