7 ms·
An API is only as good as its documentation
- pavlov 12y agoI have a corollary of sorts: A framework is only as good as its UI. 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.
- rubenv 12y agoAbsolutely, tooling is a hugely important in making or breaking any programming language/framework. In the end it all generalizes to "Your product is only as good as its experience".
- illumen 12y agoYou can have a lovely time using an API, and it could provide you results 56.786% worse than the competition. But you'd be happy, and not care.
- rprospero 12y agoI 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.
- TeMPOraL 12y agoI 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.
- beat 12y agoThe 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.
- TeMPOraL 12y agoExactly this. > 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.
- amelius 12y agoI 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.
- prottmann 12y agoNot 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.
- BetaMechazawa 12y agoI'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 requires javascript for the "full experience". https://api.pushjet.io https://api.pushjet.io Should I redo it? Are there things I should change?
- diggan 12y agoLooks 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?
- BetaMechazawa 12y agoI'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.
- yourad_io 12y agoI 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.
- BetaMechazawa 12y ago
- wantab 12y agoI'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!
- beerbajay 12y agoOh 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...
- goatandsheep 12y agoI always use archive.org to archive links so that if they break, I can always link back to them later.
- gbramwell 12y agoHi, 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.
- jkoudys 12y agoI 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.
- micahasmith 12y agoAny 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/ https://api.print.io/docs/) and "self-documentation" (http://print.io/api http://print.io/api) but i still find that we have a lot of questions.
- raus22 12y agoe.g. http://docs.themoviedb.apiary.io/#reference/collections/collectionid/get 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.
- pksunkara 12y agoYou can try using API Blueprint (https://apiblueprint.org https://apiblueprint.org) which is based on Markdown can host your API docs at http://apiary.io http://apiary.io Disclaimer: I work at Apiary
- Erwin 12y agoFor 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.
- buro9 12y agoI 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.
- shivang 12y agoA 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.
- rkn7 12y agoCompletely agree with this. I've been trying to set something up with the Trello API all weekend and it's been a nightmare.
- jfaucett 12y ago+1 for feeling your pain, had the same nightmare myself about 6 months ago.
- CyberDildonics 12y agoI would say that an API's usefulness is the complexity it hides divided by the complexity of its interface.
- jasonlotito 12y agoThe irony of this statement "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.
- baconomatic 12y agoHad to do a little searching, but here it is: https://app.ticketmatic.com/api/doc https://app.ticketmatic.com/api/doc
- rubenv 12y ago(Author here) 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.
- Sanddancer 12y agoI 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.
- jedisct1 12y agoI'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.
- ddlatham 12y agoProviding 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.
- gtramont 12y agoIt 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.
- amyjess 12y ago> no documentation is needed I would not want to code against your API.
- gtramont 12y agoDid you read what I posted? If you're writing a REST API (I advise you to read http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... if you think you know what REST is) then all you need is an entry point (much like http://news.ycombinator.com http://news.ycombinator.com) then everything else should be hypertext driven.
- amyjess 12y agoI know what REST is. 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.
- cbd1984 12y agoGood documentation includes examples. 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.
- NKCSS 12y agoI 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.
- crystaln 12y agoNot 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.
- orliesaurus 12y agorubenv what's your view on mashape.com documentation portal?