API documentation

How to Document a REST API?

The importance of a well documented API

API documentation is the interface. It’s an entry point for your customers to evaluate, learn, and to start using your API. The API space is highly competitive. Unfriendly, incomplete, or even missing API documentation can significantly damage your business.

Various personas with different motivations and needs will consult your API documentation.

API Documentation Audience

  • Developer
    • Learns how to use the API
    • Finds solutions to specific issues
  • Technical Analyst
    • Evaluates if the API meets technical requirements
  • Business Analyst
    • Evaluates the competitive landscape
  • Manager
    • Makes decisions based on technical and business analysis

Characteristics of Good API Documentation

  • Complete, accurate, and consistent
  • Well organized and formatted
  • Interactive
    • Try out functionality
    • Live endpoint status
  • Downloadable client SDKs in various technologies
    • Sample applications
  • Tutorials, Guides, Examples
  • Integrated with live support

What is the current state of API Documentation?

The importance of API documentation is well recognized. All sorts of software vendors offer API documentation solutions. Startups, small businesses, focus on high added value delivered through innovation and enterprises usually offer API documentation as a part of an API developer portal.

All of these solutions have one thing in common: A significant part of the API documentation is generated from a high-level API description.

The goal of an API developer portal is to serve various personas involved in API lifecycle by enhancing plain API documentation with other related information and capabilities such as

  • API monitoring
  • API lifecycle management
  • API test reports
  • API issue tracking

Where is API Documentation going in the future?

As the API economy matures, we will see rising demand for complete API developer portals which offer powerful integration capabilities. Also, we will see continuing attempts to fully automate the delivery of API documentation and API consumption.

In the distant future, we can expect adaptive clients using semantic API documentation to automatically adapt and to start consume APIs. The ultimate goal is to let machines learn how to communicate with each other, to establish true machine to machine communication, to minimize the human resources needed to connect software applications through APIs.

Why is Restlet uniquely positioned to address these challenges?

The Restlet API-First platform is composed of various modules covering API design, documentation, testing, automation, and data driven API deployment. Evolving existing API documentation into an API developer portal is straightforward.

Restlet has the advantage of providing various modules that cover the API life cycle. All those modules interconnected through API developer’s portal deliver great added value and allow various persons to easily accomplish theirs goals, on producer as well as on consumer side.