An example can provide a base to start from, a beginning point from which further hacking can ensue.
However, an example, like a picture, can't say "ain't": Examples can only show you what you can do, never what you cannot do, or what you should not do.
Further, examples are inductive, and it takes a massive amount of induction to get all of the rules of a system. However, once someone's done something, they've internalized it a lot better than if they've only read about it.
Examples should, therefore, allow people to see the intended use of an API. How do the developers want people to use their API to solve problems?
Documentation is permissive: "You can use this tool to do this."
Examples are normative: "You should use this tool this way."
Both are needed. I focus on examples because good examples are not as common as they should be.
I'd rather say an API is only as good as the clients/libraries for it.
Having an API is nice, documenting it is nice, but this is not what developers are going to use.
If you only publish API documentation, you will end up with tons of half-baked, soon-to-be-unsupported, incompatible client libraries.
And until then, people will have to roll their own clients based on the documentation, which is not fun. Nobody wants to reinvent a REST client, deal with errors, timeouts, data conversion and how to match the API with actual use cases.
Especially when evaluating a new service, the last thing you want is have to read an API documentation before being able to do anything with the service.
Take MySQL. The protocol is all binary, and mostly undocumented. Yet, it's used everywhere because the MySQL maintainers are shipping a C library on top on which people built bindings.
Same for MongoDB. Even though there are alternative/additional client libraries, they are maintaining client libraries for many languages. Getting started with MongoDB is easy; one doesn't have to read an API documentation at all.
What if changes have to be made to the API? If the same team maintains the reference client libraries, it can be totally transparent to users. If you expect people to write their own client, it will be painful.
Please provide good reference client libraries so that people can immediately use the service, even before thinking about API documentation. And writing client libraries is also a good way to realize what's broken/inconvenient in the API.
Providing a client or library is great, but serves to shift the actual API to be that which the client or library provides. Ultimately there is some interface between what you provide and your customer. That's the point you need to make as well understood as possible. A clean, intuitive interface and good documentation are both valuable in making it understood.
This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too.
Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.
I find your comment about Rails facinating, as it teaches me a bit about how I'm a Blub programmer.
I've tried to learn Rails multiple times and the "generate" and "console" commands have always been a massive stumbling block for me. With ever other language and toolkit I've ever worked with, the tutorial starts with opening up a text editor, writing some code, and producing a lousy, "Hello World" website. With Rails, I went through three pages of the tutorial before I even saw a single line of Ruby. I grew to hate the "generate" command, as it produced ever expanding reams of unexplained code each time the tutorial had me call it.
I had always assumed that the elimination of the need for commands like "generate" would be the top priority of the Ruby community and that their existence was a recognized design wart, like Python's GIL or Haskell's unsafe prelude. That "generate" would actually appeal to someone is something that I'd never even considered. That makes me a Blub programmer and tells me that there's another whole philosophy of programming that I need to learn about.
I don't think this is about being a Blub programmer. Rails is a complex web framework that is designed to help solve many common problems in web development. Therefore, it has tons of code organized in an arcane way you won't understand until you know what problems it's trying to solve.
That's why I always found teaching RoR (or equivalent frameworks in your language of choice) to beginners completely backwards. What the newcomer learns is how to tweak this huge blob of arcane magic here and there, and gains almost zero actual understanding of how things work. My preferred way of teaching webdev is showing how text goes from server to browser, how the browser parses it to render a page, and how a programming language is used to generate such text. And then I build up from this base. Sure, this approach won't make one a Rockstar Full-Stack Code Ninja in half a week, but at least the student has some solid foundation of understanding to work from and can comprehend why Rails looks the way it looks.
It also seems to me that the current trend in web development is people using huge complex tools, of which they need 1% and understand 0.1%, and thus generating layers upon layers of bloat. But my opinion here is probably biased as I hate webdev more and more with every single day I spend working in it.
The problem, then, isn't that we shouldn't use complex frameworks like Rails, but rather we shouldn't teach with frameworks like Rails. In order to teach Ruby-based web development to the n00bs, use Sinatra. This forces them to address the Ruby language right away, learn http verbs, learn unit testing (well, if I'm teaching them anyway), learn templates, and learn to organize code from a single file up to a simple structure like a gem.
Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
> Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
How the magic works, and why it's needed in the first place.
"At Ticketmatic, we promise that anything you can do through the user interface is also available via the API."
in the context of the article is amusing. Going to the website, I find no mention of an API anywhere. I can only guess that it's API documentation hidden behind a login. This is the worst kind of API documentation. I've dealt with APIs like this far too often to find it friendly. In every case, it's been frustration.
Regardless, while the platitude is agreeable, this is literally an article that says nothing more than what fit into a tweet.
Nope, that's the old one for V2 (which isn't very good).
We're currently releasing the third generation of the Ticketmatic platform, where one of the big efforts is in improving the developer story.
That's not public yet, for which I apologise. There will be a beautiful developer program soon.
I didn't think that the article should wait on that. It's the idea that matters and didn't want any discussion to turn into a nitpicking over what we did right (and wrong).
This article mostly came out of a frustration with bad API documentation and I was hoping to inspire people to do (slightly) better.
I think that your redevelopment of API documentation would be an interesting series of blog articles in and of themselves. Giving examples of bad documentation decisions, giving examples of how they were corrected in the new documentation, etc. There are lots of examples of refactoring code, but entirely too few that deal with refactoring the manual.
Any recommendations on good doc frameworks/products?
We're about to begin redoing our documentation at print.io. Currently we're using swagger (https://api.print.io/docs/) and "self-documentation" (http://print.io/api) but i still find that we have a lot of questions.
Thanks for the tip, Tim! Happy to answer any questions folks have about my product.
Also, plugging: Swagger support in just a few weeks. And we can currently auto generate endpoint reference docs from your source code using a commenting standard similar to javadoc.
We get all sorts of excited by good API documentation. Weird, right? Apparently not, based on this thread. :D
I find all of the auto-generated systems produce barely sufficient documentation.
Real documentation is written by a person who understands how to use the API.
Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated.
What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.
For our corporate API, we the Apiary markdown with aglio to convert into nice documentation. I've tried RAML (I didn't like the giant YAML file) and apidoc (I didn't like to put 100 lines of user documentation next to 20 lines of implementation). I use protagonist to convert the md file to JSON which my Python code can load and compare with the decorated API endpoints -- I can then verify they and all their parameters are properly documented. I don't use the fancy Apiary features yet.
We're using swagger to great effect, the ability to add markdown against the endpoints allows us to describe them with both relevant documentation and examples.
e.g. http://docs.themoviedb.apiary.io/#reference/collections/coll...
where TMDB use apiary, and with quick examples with the different inputs and outputs. So you can test it out right away WITHOUT needing to find ID's to use for test. This provides real response values, as to know what you get when you send some value.
I wish we could have "documentation day" on github, where all project maintainers would spend one whole working day on documenting as much as they possibly can.
Not enough. Its more fun to create software, but documentation is the part that no one likes.
It is absolutely necessary, in particular when other work with your code.
And we have many stages of documentation: the project documentation (what is it, what does it, how, ...), the code doc, the rest-api doc. And it get really complex on further development.
I think that is one reason for the small JS project explosion on npm / github of the last years.
A very valid point raised by the author. Having worked with multiple api's i can say that developers start preferring that product which has better api docs than the other product which has a crappy doc inspite of having many features.
I was working with PayPal few years back and there are bunch of apis that they provide, but the explanation and usage is so bad that you end up spending a lot of unnecessary time figuring out what to do.
And then i came to Stripe integration. They have beautiful apis which can be integrated smoothly and very easily. I tell developers to follow Stripe's api for writing documentation and examples.
I'm currently working on a libre push notification service (Heavy WIP) and since this post is about API's and Documentation I was wondering if mine is any good.
It's really not even close to being verbose enough. A good API doesn't just give you the name of the endpoint and what it's expecting - it should explain what the endpoint is for. Your documentation assumes the user already knows what they're going to implement in terms of your API (eg they know that they'll need to create a 'service' that other clients will 'listen' on, and so on.
Also, what's especially unhelpful in your documentation is the fact your example code returns errors. In the /listen POST documentation clicking the Send button displays
{
"error": {
"id": 4,
"message": "Already listening to that service"
}
}
I assume that means it's already connected, but should that be the case in an example of creating a connection?
The API documentation is talking to the live version of the application. The pre-filled variables can be used for quick testing but this also means that when you make the default user (UUID) listen to the default service it will tell you that it's already doing that. Changing the UUID should be sufficient to give it a non-error response for that API call.
I'll add some documentation about what endpoints do and what kind of "flow" an application needs to interact with the API when I get home from work. I'll also finish my quick start guide while I'm at it then.
I would add a few paragraphs introducing it and giving some common examples/use cases.
I like your "try-this-request", however IMHO it is missing a "request is in progress..." kind of indicator - clear the output space and add a spinner? I had to look in the developer tools to ensure that it works.
Finally, not all things work: 'Websockets/Run Example' doesn't do anything. In the background there is a 500: 'WebSocket connection to 'wss://api.pushjet.io/socket' failed: Error during WebSocket handshake: Unexpected response code: 500'. In your defense, you do mention that "Websockets are really iffy at the the moment and are currently in the process of being redone". But still, better capture that error and show it somehow.
All in all, ahead of the curve ;) Some UI lovin' would put you at the head of it.
Thanks a ton! I've always been annoyed by the fact that Web API documentations never had a "try-this-request" feature. I'll get right to expanding the documentation when I get home like I said in the other comments. The request in progress indicator should be pretty easy to add. Totally forgot about it. I disabled the websockets example because It's currently undergoing a complete rewrite.
Looks simple and good to me. However, on first glance, it's missing some quickstart guide/introduction and how to authenticate. Also, some calls seems to return nothing at all, is that correct?
I've written a draft for a quick start guide using python/javascript (code with comments). I've been withholding publishing it because it's not fully done yet and message queues and the android app (only thing to do is the Matrial UI) are my #1 priority at the moment.
One of the main ideas behind the service is that there is no authentication. You just generate a persistent UUID and use that.
I think it's when you try to separate code and documentation that things tend to get out of sync quite easily.
For example; we have a settings system; all keys are defined as constants in code and they have attributes that clearly describe every aspect which is the used to generate the documentation. If you add a new settings, you instantly write the documentation for it as well; so far, it has worked great and I think this could/should work for other parts of the code as well.
It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.
The problem with this "no documentation" stance, as you've seen below, is that it doesn't get the correct message out to those who haven't studied hypermedia.
I like to make an analogy to RSS: If I told you, "Here's a link to my RSS feed." You wouldn't be mad at me for that, since all you need is RFC 822. By the same token, hypermedia/"real REST" APIs don't have _no_ documentation: they have no _specific_ documentation about _this_ particular API.
Without a foundation in this approach towards building and consuming APIs, "no documentation" sounds like a disaster. And it is, in that context.
My premise was, when I wrote the first post, that REST is understood. Not a surprise that it is not…
I totally agree with you… And what I've been trying to do to whoever I talk to, in my team and outside, is to educate them in this area (sending resources like I did on an earlier post), and try to make them not call any json-based API REST (which in fact has nothing to do with json specifically).
Congratulations, I now have a URL and a JSON file the URL spits out.
I still have no idea what the significance of all the values are. I have no idea what their possible ranges are. I don't know how everything works together.
Edit: Also, that's just GET. If you expect me to poke around with POST to learn how your API works, I will run far, far away.
REST as defined in the original papers, REST as defined by your link, and REST as actually used in practice are all somewhat different.
Even in your link it is plainly obvious that there is no provision for documenting what an endpoint does, or how to find what endpoint maps to something, or even how to query this magical introspective API to figure out what further requests you need to make.
Everyone in this thread needs to up the civility and charity a couple notches. I think what's at heart here is a disagreement about what exactly is required by HATEOAS. I'd like to hear people expand on that.
Not to discount the importance of good documentation, but this is not true. Many of the best uses of APIs historically have actually come from reverse engineering undocumented APIs.
I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them.
For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you're in a loop.
So then you try their search function, or Google, but then you find yourself linked to either outdated docs that look like the same thing or articles about the subject which give no detail.
It's spaghetti documentation mixed with out of date spaghetti mixed with meatballs. At this moment, I have 13 tabs open to various parts of the docs trying to piece things together to understand how to make it work and, sometimes, I find the out of date docs more understandable!
Hi, I'm one of the devs working on the Braintree docs. You're absolutely right, the information flow in our docs isn't in a great state right now.
We're actively trying to fix the flow issues by consolidating information so you don't have to go tab-hopping to find what you need. If all goes well, hopefully you'll see some improvements showing up very soon™.
If there's a specific problem you'd like to share, I'd welcome the feedback. Either way, we'll keep forging ahead on another rev that's a little easier to follow.
I had a similar experience with the Eventbrite API. The docs looked well-written, and early usage was promising, but then you have to get almost to the end of your implementation before realizing the missing components. In my case, EB allows what's called a "repeating event", or an event that occurs on multiple dates. However, their response JSON doesn't have anything like `{times: []}`, rather it's just `{start: {}, end: {}}`, so you never have a set of the dates. There _is_ a 'repeats: <boolean>' property in the response, but that is permanently set to false, and if you have a repeating date it appears as a single-date event where the start and end times are for the next upcoming date.
I would have been better off if they didn't supply that doc at all. If I just fumbled my way through an undocumented pile of service endpoints, I'd have realized its limits much sooner. The doc gave me the false-confidence to build my application based on behaviours in their API which aren't actually implemented.
Oh god, salt-stack is just like this. Lots and lots of documentation which looks great at first, but once you actually start using it it's frustration after frustration. The poor typography and use of YAML doesn't help...
Good documentation does not rely on examples.
An example can provide a base to start from, a beginning point from which further hacking can ensue.
However, an example, like a picture, can't say "ain't": Examples can only show you what you can do, never what you cannot do, or what you should not do.
Further, examples are inductive, and it takes a massive amount of induction to get all of the rules of a system. However, once someone's done something, they've internalized it a lot better than if they've only read about it.
Examples should, therefore, allow people to see the intended use of an API. How do the developers want people to use their API to solve problems?
Documentation is permissive: "You can use this tool to do this."
Examples are normative: "You should use this tool this way."
Both are needed. I focus on examples because good examples are not as common as they should be.