Introducing the DigitalOcean OpenAPI Specification

Posted 2021-03-30  in Engineering
blog header

When v2 of our API first entered general availability in April of 2015, it consisted mainly of features supporting Droplets and domains. Since then, DigitalOcean’s product portfolio has grown, and the surface area of our API has greatly expanded along with it. Today our API supports App Platform, databases, firewalls, Kubernetes, load balancers, and more. Providing over 200 operations, our API enables you to do just about anything you can do in our control panel programmatically.

Keeping up with all these changes can be challenging. That’s why we’re excited to announce the release of a new tool to give you confidence when developing against our API: the DigitalOcean OpenAPI Specification.

What Is OpenAPI?

OpenAPI is an open standard for describing APIs led by the OpenAPI Initiative. As the specification itself reads:

  • The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
  • An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Internally, an OpenAPI specification provides engineering teams at DigitalOcean a common language to define and collaborate on API design. It also defines a formal contract that can be tested and monitored, ensuring that our API remains stable. By publicly releasing the specification, it provides customers with new ways to interact with our API.

Open Source

The source files for our specification are now available on GitHub. The repository also includes tooling to work with the files. For example, to check out the repository and compile the specification into a single file, run:

git clone https://github.com/digitalocean/openapi.git
cd openapi/
make bundle

You can use the specification to generate Postman Collections, mock servers, and API clients in languages we do not yet officially support.

Feedback

The specification is currently in Early Availability. While the specification is accurate, it is still under active development. The structure of this repository may continue to evolve. If you encounter any inaccuracies or have feedback on how it can better suit your use case, please let us know by opening a GitHub issue.

How do you hope to use the specification? What kind of tools would like to see for working with the DigitalOcean API? Let us know in the comments below!