API Design
January 17, 2020

What Is API Design?

API management

While APIs can unlock new business channels, create value, and ignite a digital transformation when created properly, APIs can also be your biggest enemy when poorly designed.

In this blog post, we’ll cover the fundamentals of API design and how the Akana API management platform simplifies the process to ensure that your APIs are easy to consume, built the right way, and running as they should be.

Definition of API Design

API design is defined as the process whereby application programming interfaces (APIs) are created, connecting disparate technologies by exposing application functionality and exposing data for use by consumers and developers.

How an API is designed has an important impact on how it is used by consumers and developers. As detailed on Wikipedia:

The principle of information hiding describes the role of programming interfaces as enabling modular programming by hiding the implementation details of the modules so that users of modules need not understand the complexities inside the modules. Thus, the design of an API attempts to provide only the tools a user would expect.

Akana API Design Features

APIs are all about the user (consumer or developer). One key to providing a good user experience is an intuitive developer portal that allows API developers to design, build, and document well-constructed APIs.

The Akana API management platform provides flexibility and productivity for API designers, making it easy to create simple, secure APIs in the descriptor language of your choice.

Key featured, as touched on in a previous blog, include:

  • Design and document APIs with a powerful, easy to use interactive graphical editor for authoring APIs from scratch, or viewing and editing an imported API. The designer also supports markdown to add rich documentation.
  • API descriptor import: allows the designer to import multiple different versions of Swagger, RAML, WADL, and WSDL. New in a 2019 release, the API Designer also supports dynamic switching between OAS 3.0 and Swagger 2.0.
  • API descriptor generation: regardless of how you defined an API, whether with the graphical tool, or by importing a description, the Akana platform allows your consumers and developers to export your API definition in whatever descriptor language they choose.

Resources (Operations)

For each operation in Akana’s developer portal you can set up two basic types of information:


  • Path
  • HTTP verb
  • Operation ID (a unique ID for the operation, user-defined)
  • A brief summary
  • A longer description, if desired

Technical Details

  • One or more parameters, including:
    • Name
    • Description
    • Type
    • Whether required / if not required, a default value, used if the user doesn't specify a value
    • Whether empty values are allowed
    • Data type
    • Format
    • Minimum length
    • Maximum length
  • One or more response types, including:
    • HTTP code
    • Description
    • Data Type: string, number, Boolean, integer, or array

We encourage you to view our past webinar, API Design Essentials, which provides an overview of the Akana platform and walks you through a demo of how to design APIs.

Next Steps

See Akana API Design in Action

Now that you have a better understanding of what API design is and how it is performed in the Akana platform, give it a try yourself!

Sign up for a free 30-day trial with Akana and learn how to create, document, test, and secure an API.

Start Trial