If the answer to the above question is yes, then please read the following carefully. You're development community will thank you.

I love working with API's. The ability to take disparate bits of information and remix them into something new and awesome is why I still develop as much as I do. While this is true, working with APIs isn't always a fun, positive experience.

My recent work with the API for AgileCRM is a great example. Half the features aren't documented at all, and those that are, poorly so.

Oh and about documentation:

When I load the documentation for an API, I want to find what I need, as fast as possible and get back to writing code. The best way to do this is not only have thorough documentation about the code itself, but a clear, real world example of using the API method or function that you are highlighting.

Let's look at a practical example from my Habari plugin exportinator.

Not too bad right? Gives you what all the options are, and hopefully clearly states all the info you need to use the plugin. I could have stopped there, which is what most people do, but I didn't.

There are a lot of people out there who aren't great at reading documentation. They need visual examples of using the code to really understand how it works and why, which is why I also provided this:

$document = Document::get( array('id' => $vars['document_id']) );
$pages = Pages::get( array('document_id' => $document->id) );
$objects = array( 
'document' => array(
'content' => $document, 
'fields' => array('title', 'slug', 'content')
),
'page' => array(
'content' => $pages, 
'fields' => array('title', 'slug', 'content')
)
);
$assets = array( 'style.css', 'prettify.css' );
$args = array(
'connected' => array('parent' => $document, 'items' => 'page'),
'export_name' => $document->slug,
'template_types' => array('document', 'page'),
'template_location' => DIR . '/export_templates',
'objects' => $objects,
'export_location' => 'exports',
'assets' => $assets
);
Exporter::parse( $args );

With this code block added, showing real, understandable data, a new user to the plugin should be able to jump in and start hacking. Which leads me to the reason for this article. The Github API.

I am working on a plugin for this site to allow me to backup all of my posts as individual JSON files to a publicly accessible repo on Github. I was reminded last week that this site has been around for what seems like forever, and there are some pieces of content that are worth archiving for posterity.

Thoughts and code snippets from the early days of WordPress for example. Not to mention from a strictly personal, legacy standpoint, the thought of losing all of this writing, covering more than 16 years is mildly panic inducing.

I have already suffered a catastrophic loss of comment data from the first 8 years of the site's life, even though I had backups. You just never know what's going to happen. So, enter GitHub.

I am writing the code myself, since I prefer to know what is going on when I am connecting services together, not to mention the fact that Habari already provides a number of services that most frameworks duplicate.

I hate that stuff. I just want what I need. So things are going okay, and then I hit a wall. An error response wall. It seems, for some reason, GitHub has decided to return a 404 error for a number of scenarios that are not 404 related. The one that matters in this scenario are when authentication fails.

While this seems like an okay idea, return a 404 to protect account data, and exposing the existence of account info to nefarious people, in practice it is incredibly frustrating.

I am hitting it when I perform a POST action on the API, but not when I perform a GET. And the error is useless. It just says "404 not found" essentially.

This is hostile to your developers. I get the desire to protect user info, but how am I supposed to debug what is going on? I could install software that inspects the requests, etc but the overhead involved is absurd for this one thing.

HTTP error codes are there for a reason and with very few exceptions, should be respected. Also, for the love of all that is holy, have a flag I can send along with my request that says "Hey, this is a developer so give me actual, useful data about why this request is failing so I can actually fix it."

It's not that hard people. It's not that hard.