June 9, 2014

“An API is a journey, not an endpoint, and always a moving target.”
-John Musser

I thought I would write about what we intend to do to help make Mojio’s API a professional, but well liked and useful platform for developers. We are taking our cues from established REST API’s like Stripe, Twillo, SendGrid, GitHub and Heroku. We want to make our API clear and understandable and easy to use.

MOJIOPeriodicTable_Events

Of course, this is easier said than done. We have lofty goals, for sure, but below is our list of what we aim to do.

I recently attended APICon and heard a talk on Hated API’s and why they are hated, by John Musser, who reinforced a lot of what we have been intending to do. I have taken some pointers from him to format this blog post following his 10 key points.

Reason 1: Good Documentation.

Documentation should be like a GPS, it get’s you to where you want to go, doesn’t divert you down alleys and to places you don’t want to go. It get’s you there quickly. The desire is to get to the sweet spot of “not to much,” “not to little,” and a clear navigation hierarchy that gets you to an answer quickly. It also must be updated and accurate.

Our working model for our API documentation navigation items fall into five categories clearly separated from operational concerns like managing your application or getting support:

Documentation:

  • Overview Topics: introduction, security, access, domain, vehicle data, etc.
  • Quick Starts: Short, simple guides to get started using Mojio
  • How To’s: Example code and use cases
  • Vehicle API: Documentation of the vehicle REST and Push API’s
  • Helper Libraries: (Clients: C-Sharp, javascript, php, python, Java, ruby, etc…)

Dashboard:

  • My Account
  • My Applications
  • My Simulator

Community:

  • Support
  • Forum

The idea here is to show the big picture first, keep everything above the fold and keep the menus big and clearly available when you land on the developer site. Also, the intention is to provide helper libraries in as many languages as possible so many different kinds of developers can easily get started without having to dive into the intricacies of the REST http calls.

Documentation on the API will be “live” allowing developers to try the REST calls as they learn them, or run and modify javascript code right in the browser in the examples.

Reason 2: Keep developers informed

Here, the goal is to inform developers in several channels of any changes to the API, breaking or not so that they aren’t surprised by anything. Versioning will keep obsoleted calls around for a while giving time to adopt improvements in the API.

Channels that we intend to use include:

  • Change Logs
  • A Roadmap of changes coming
  • Release Notes
  • Blog
  • Forum
  • Direct Email for registered developers.

Messaging should be succinct and to the point, just what developers need to know about the API or their applications. The goal will be to have graphically rich and clear messaging that shows what’s coming on a monthly basis.

Reason 3: Make writing applications easy

How fast developers can write their first application is very important. The signup should be easy and they should be able to grab some code in their native language and it should just work and do something useful. For Mojio, that means authenticating the user and making a request to one of the domain model endpoints like “GET vehicle” for a user and “GET trips” for that vehicle. API keys and the maintenance of applications should not require much effort to obtain and make work.

TTFHW (Time to first hello world) should be quick and easy.

In order to make it easy there needs to be a “just the facts” 1-2-3 style tutorial, do these three things and you have something working: sign up and get your keys, download the code, run. Copy paste and go, or run and edit right in the browser.

Beyond the first application, the vehicle domain needs to be clearly pictured, so that how resources are related in the REST API is clear and the purpose of each resource is obvious.

There should be a variety of languages and each project in those languages should be available in a variety of integrated development environments,

Reason 4: Make the legal stuff easy to understand

The terms of service need to be very clear, and if legal ease or fine print is required, there should be a plain English description of the intent of that wording. Shorter is better. We intend to be up front about what the API does, and how the developer benefits from using it.

Some things we intend to show in the terms of service are: The value proposition, The deprivation policy, business model, service level agreement and any limitations.

Reason 5: Reliability

Our intention is to provide a bug free, fast and reliable platform with clear road maps for changes and accurate documentation. The effort will be to remove a feature only after it has been deprecated but still available for a fixed period of time, measured in months.

When errors do occur, messaging should be helpful without stack traces and noise so that the developer will know what action to take in response to problems.

Mojio’s API is hosted on cloud based redundant systems that automatically scale up with heavy usage. Deployments are vetted in staging environments with unit, functional, and regression testing.

If something does break we intend to inform developers of the problem and provide a timetable for repairs. We don’t need or want to hide problems when they occur. The state of the platform must be monitored and freely available to anyone working with it.

Reason 6: Give developers tools to succeed

Because the API implements and interfaces to physical cars, testing interactions and making applications work is difficult. That requires a certain amount of tooling to simulate data coming from vehicles. We provide a sandbox environment with a vehicle simulator and tools to manage resetting of test data within the sandbox. This provides an easy way to see if an application is performing as needed.

Each developer will have their own dashboard where they can track usage, manage their application, manage testing, and gain visibility into their application’s behaviour.

We also are using OAuth 2 as a mechanism for authenticating users. This is an industry standard for registering and authenticating users in a federated environment.

Reason 7: Don’t market to developers

Developers hate marketing materials. They just want the facts and the reasons why they should use your API. They want code, not white papers. They want information, not sales pitches. How does it work? How can I do what I need to do? Is it useful to me? These are the main questions they need to answer.

Typically, if you have made it to the API documentation, you have already decided that it might be able to help you and the question you are answering is “how long will this take”, and “how does this work”? Through answering those questions by doing, you will be sold and you have created something easy and useful in your first visit.

Developers typically want self-service access to the documentation, code, and management of their processes. Having to call someone to get something started is a definite turn off. However, once started, having help available either through forums, support channels, or excellent documentation is invaluable. It’s especially valuable if the documentation answers questions quickly without having to resort to forums or support.

Any marketing we will do to developers will be in the form of “hackathons,” conference presentations, or developer contests, and, if they really want to be sold, they can go to the main Mojio website, clearly separated from the developer site.

Resaon 8: The API is simple, not complex

We intend to expose every corner of our API, even the restricted bits, as a policy. But we also intend to expose the “cannon” of API calls that represent the most useful functionality to developers, making it easy to find 95% of what you need to do right away.

The API will conform as much as possible to REST constraints, with special attention to the uniform interface, and statelessness. Data is returned in JSON format, the current standard for data transfer objects. The intention is to satisfy hypermedia constraints of the uniform interface. All of these things make the API more easy to understand and access.

Reason 9: Finally, we intend to learn from the best

Our models are: Stripe, Twilio, Github and SendGrid.

That’s our roadmap, our wish list to make Mojio’s API well loved and used within the developer community. Let us know what you think and how we are doing because we only get better with feedback.