openapi or similar machine readable definition of api?

[erichelgeson]

It looks like the API docs are built off of some definition, could that be shared? It'd be nice to automatically generate http clients off of it instead of copying/pasting.

[bentranter]

Hey @erichelgeson, despite the appearance, our API docs are built out quite manually. That said, our team is working on creating and publishing and OpenAPIv3 spec. We don't have a release date planned for it just yet, but I'll keep this issue updated with our progress.

[danielgtaylor]

@bentranter any updates on this? It would be nice to have the OpenAPI 3 spec.

Also, since you may be actively working on this, I wanted to point out a couple nice-to-haves:

1. RFC 8631 defines a service-desc link relation header you can use to link to your OpenAPI file from the API's base URI. This allows for client discoverability of the API description.
2. If you adopt the above (or describedby or make the OpenAPI available at https://api.digitalocean.com/v2/openapi.json) then also please consider adding a badge. This lets everyone know that the Restish CLI just works with Digital Ocean's API. See also:
   • https://dev.to/danielgtaylor/a-cli-for-rest-apis-part-1-104b
   • https://rest.sh/

This is my current Restish configuration for Digital Ocean in ~/.restish/apis.json:

{
  "do": {
    "base": "https://api.digitalocean.com/v2",
    "profiles": {
      "default": {
        "headers": {
          "authorization": "Bearer **secret hidden**"
        }
      }
    }
  }
}

[Verolop]

@danielgtaylor thanks for your input.
That's right, we're currently actively working on it, so all external input is welcome. We don't have a release date yet, but it's now a reality :)
Pinging @hilary to get her thoughts, as she is leading this project.

🙏

[hilary]

We're starting to build out the spec. There's a repo now, apiv2-openapi, where the spec will live. The first couple of endpoints will go live any day now (really).

[hilary]

@danielgtaylor I will take a look at Restish, although it won't be for at least another month. We've been buried in figuring out a toolchain that is dev friendly, well supported, and open source that will let us build out a spec for our current APIv2 that will be useful for our dev community as well. It's been a journey, but the result is nice.

[glennjacobs]

Is there any progress on this? An OpenAPI would make things so much easier.

[bentranter]

Hey @glennjacobs, yep! Our entire (small) team is actively working on this, with it currently being our highest priority item. One of the goals of creating an OpenAPI spec is to make it possible to generate API clients (as you mentioned in the linked ticket), and we're expecting to have that work done before the end of this year. I'll update this ticket again once we're in a position to commit to more certain release date for the spec.

[bentranter]

Hey everyone, we've just open sourced our spec for early access https://github.com/digitalocean/openapi. If you have any questions, feel free to comment here.