API design

How to Design a REST API?

The Problem: Poor-Quality APIs Damaging Businesses

With customers demanding information in real-time, APIs are among a company’s greatest assets and liabilities today. At the core of API design are specifications used by developers and customers to establish communication between software applications. Poor quality APIs risk breaking existing integrations. Once it’s public, it’s public forever.

To be successful in the digital economy today, you need to understand these three API problems:

  • Customers and developers have large investments in learning, adopting and integrating your API
  • Breaking a public API with a version change costs you and your customers time and money
  • Bad API design causes unending support requests and damage to a company’s reputation

The Solution: Good API Design

  • Good API design allows API development parallelization (e.g. users of the API can build applications at the same time that the back-end services are being developed)
  • Good APIs capture customers and are sold as a product today

Characteristics of Good API Design

  • Easy to learn and use, even without documentation
  • Easy to extend
  • Hard to misuse
  • Satisfies all requirements

Current State of API Design

Today, API design is driven by the code-first approach of software development. A backend is implemented first and an API mostly reflects how the backend works internally. The main disadvantages to this approach are:

  • Any change to the backend may cause API breakage. It’s hard to evolve and to extend
  • Development cannot be parallelized
  • API design cannot be easily adjusted, extended, or polished. It’s driven by an implementation
  • Consumer’s needs are not directly reflected. It’s hard to satisfy all requirements

Contract-driven design is a new way to design APIs. Contract-driven design moves the focus away from an implementation on the contract itself. It solves the main issues of the code-driven approach. Contact-driven design can be done with a domain-specific language or more easily with a tool allowing visual API design creation and maintenance, like Restlet Studio.

The Future of API Design

In the future, API design tools will generate high-quality APIs from requirements and high-level use cases, describing not just the API but the whole product. The generated APIs will follow best practices out of the box. The API design, and the API itself will be more hidden, but still easily accessible if needed. Good API design requires advanced skills. The learning curve is high. Next generation tools will push the learning curve down, enforce best practices, and enable sharing a good API with a broader audience.

Why is Restlet uniquely positioned to address these challenges?

Restlet’s mission is to provide you with the fastest and easiest way to deliver APIs. In the new API economy, having good APIs is crucial. An API is your public facade and a product you sell. Restlet Studio offers a visual way to design and maintain an API. The learning curve to use Restlet Studio is low. Even if you are not a software development veteran, you will be able to create good API designs.

With the Restlet Platform you can also easily turn an API design into documentation or even into API tests.