I worked as a developer at a company whose main product was an API, so I definitely have some thoughts. Your list of features seems reasonable to me, but in my opinion the most important questions are more subtle.
There's a crucial step that's easy to overlook: Make sure you have a solid plan for how you're going to update your API. The ideal is a versioned API, where old versions are supported indefinitely. If that's not plausible for you, consider how you're going to communicate changes to developers with enough lead time for them to update their apps. (And you'll still want to version things, because it's no good to make everyone deploy at the exact same time as you.) Remember that since you don't have control over third-party code, even changes that seem totally innocuous to you might break things.
It's often hard for a web company that's used to agile-style fast release cycles to get in the proper mindset for maintaining an API. The ideal is for breaking changes to be rare, and done with a lot of lead time. This can of course be different in a beta period, but communicate that heavily and plan to lock things in eventually.
Related to the above, try to give good error messages when things go wrong. There's a big difference between "our servers are having trouble right now" and "the route you're using doesn't work any more". Developers won't have access to your server logs, so they'll be relying on you for debugging information.
Thinking about the business side of things is also important. Start thinking now about what sort of apps you'd be tempted to try to shut down, and whether you're going to do that. Try to come up with a terms of service that you can live with for a long time, because nothing makes developers more wary of a company than them shutting down any third party service that gets too popular.
Get all of that right, and you'll be head and shoulders above 90% of APIs out there. :)
There's a crucial step that's easy to overlook: Make sure you have a solid plan for how you're going to update your API. The ideal is a versioned API, where old versions are supported indefinitely. If that's not plausible for you, consider how you're going to communicate changes to developers with enough lead time for them to update their apps. (And you'll still want to version things, because it's no good to make everyone deploy at the exact same time as you.) Remember that since you don't have control over third-party code, even changes that seem totally innocuous to you might break things.
Couldn't agree more, we plan to keep meticulous documentation, version control and a moving forward only approach with new API versions. We realize that changing even the most trivial functionality in the API can cause issues.
It's often hard for a web company that's used to agile-style fast release cycles to get in the proper mindset for maintaining an API. The ideal is for breaking changes to be rare, and done with a lot of lead time. This can of course be different in a beta period, but communicate that heavily and plan to lock things in eventually.
Yes, we do plan on having a beta period dedicated to working out the kinks.
Thinking about the business side of things is also important. Start thinking now about what sort of apps you'd be tempted to try to shut down, and whether you're going to do that. Try to come up with a terms of service that you can live with for a long time, because nothing makes developers more wary of a company than them shutting down any third party service that gets too popular.
Get all of that right, and you'll be head and shoulders above 90% of APIs out there. :)
This is all great. I've worked with the API's on the product I work on at my job (for automating repetitive tasks) and having useful errors is one of the biggest problems I ran into when trying to accomplish a certain task. Having a versioned API is also a must or API users will be scrambling to find out when a new version is released.
I worked as a developer at a company whose main product was an API, so I definitely have some thoughts. Your list of features seems reasonable to me, but in my opinion the most important questions are more subtle.
There's a crucial step that's easy to overlook: Make sure you have a solid plan for how you're going to update your API. The ideal is a versioned API, where old versions are supported indefinitely. If that's not plausible for you, consider how you're going to communicate changes to developers with enough lead time for them to update their apps. (And you'll still want to version things, because it's no good to make everyone deploy at the exact same time as you.) Remember that since you don't have control over third-party code, even changes that seem totally innocuous to you might break things.
It's often hard for a web company that's used to agile-style fast release cycles to get in the proper mindset for maintaining an API. The ideal is for breaking changes to be rare, and done with a lot of lead time. This can of course be different in a beta period, but communicate that heavily and plan to lock things in eventually.
Related to the above, try to give good error messages when things go wrong. There's a big difference between "our servers are having trouble right now" and "the route you're using doesn't work any more". Developers won't have access to your server logs, so they'll be relying on you for debugging information.
Thinking about the business side of things is also important. Start thinking now about what sort of apps you'd be tempted to try to shut down, and whether you're going to do that. Try to come up with a terms of service that you can live with for a long time, because nothing makes developers more wary of a company than them shutting down any third party service that gets too popular.
Get all of that right, and you'll be head and shoulders above 90% of APIs out there. :)
I worked at one where the product was available 100% through an API and where our own interface used only the public API.
The most overlooked piece of advice I can give is : look out for typos, you're going to look silly for a very long time otherwise!
Also, your API stability (alpha, beta, stable) may be per path so you can advise users of what is just a test and have their feedback.
Definitely a good call about the typos!
Couldn't agree more, we plan to keep meticulous documentation, version control and a moving forward only approach with new API versions. We realize that changing even the most trivial functionality in the API can cause issues.
Yes, we do plan on having a beta period dedicated to working out the kinks.
Some great advice here, thank you.
This is all great. I've worked with the API's on the product I work on at my job (for automating repetitive tasks) and having useful errors is one of the biggest problems I ran into when trying to accomplish a certain task. Having a versioned API is also a must or API users will be scrambling to find out when a new version is released.
I would definitely be interested in helping!