DO Ideas 2

Expose a *really* RESTful API

I was trying to create a library to access DigitalOcean's RESTful API but I found that it's not a RESTful API. You expose an API via HTTP, but it is not RESTful (read more about it on https://en.wikipedia.org/wiki/Representational_State_Transfer).
Some things that must change to call it RESTful are:

- Use more HTTP verbs than GET - GET should be used only to *retrieve* information, like list droplets (it's idempotent), never to *change* information (like add a new droplet).

- We don't need a "status" in the response body. Use HTTP status code for it. A HTTP 200 represents an "OK", so we don't need "status": "OK" in the body. The body should have *only* information about *the resource* I'm accessing. An example: "/droplets" should answer with a JSON containing only droplets, like: "[{...info for droplet1...}, {...info for droplet2...}]"

- Operations like "new", "edit" and "delete" should use HTTP verbs (POST, PUT and DELETE, respectively), not different URIs. Examples: to delete a droplet I must do a DELETE request on "/droplets/DROPLET_ID" (without body) instead of doing a GET request on "/droplets/DROPLET_ID/destroy"; to enable backup on a droplet I must do a PUT request on "/droplets/DROPLET_ID" with a JSON body like "{'backup': 'enable'}" (other operations like reboot, power cycle, shutdown, power off, power on etc. should be accessible the same way). The resources' URI and verbs for SSH keys and images should follow the same concepts.

- Last but not least: it's not related to REST, but I think you can improve the way we pass regions and sizes to your servers. We *don't* need to know which ID the size "512MB" has in *your internal database*. I should only pass "512MB" as the "size" parameter and you should take care of its ID to store it internally (it's ok to have IDs for droplets and images since it's the only way to uniquely identify them).

  • Álvaro Justen
  • Sep 11 2018
  • Shipped
  • Sep 11, 2018

    Admin Response

    Sorry for the long wait, but we have finally launched our new v2 API publicly. Please note that it still has the "Beta" flag which means that we may make some large changes that may break some functionality but we are eager to get feedback from customers so that we can finalize this new version and release it as a general release. We have a blog post up that covers some of the details and provides links to getting started guides in our community: https://www.digitalocean.com/company/blog/api-v2-enters-public-beta/ We are also collecting issues, bugs, and recommendations via github: https://github.com/digitaloceancloud/api-v2 Some large updates that are included with v2 are: 1. Fully RESTful not GETful ;) 2. OAuth by default (easier to build third party tools) 3. Support for multiple tokens with read and/or write access After we move this to a general release we will then begin adding additional functionality that has already been requested here in UserVoice such as more account information and functionality as well as more billing information. Thanks!
  • Attach files
  • Álvaro Justen commented
    September 11, 2018 19:23

    Version 2 API is REST! \o/

  • Anonymous commented
    September 11, 2018 19:23
  • Ajnasz commented
    September 11, 2018 19:23

    I would also like to be able to create a web application without any back-end, but for that I would need to be able to send CORS ( http://en.wikipedia.org/wiki/Cross-origin_resource_sharing ) request. For that please add the Access-Control-Allow-Origin HTTP header when you do the new API.

    Thanks!

  • Filip Oščádal commented
    September 11, 2018 19:23

    I would vote for complete REST API using Headers and HTTP methods correctly.

    For really disastrous operations like DESTROY I would vote for a 2-step process requiring a verification code POST. You do not destory droplets on a minute occasion...

  • Bob Blanchett commented
    September 11, 2018 19:23

    Dear DO, spend a tiny bit of money and get apigee.com to have a quick look at your API.
    API consulting is all they do and theyŕe BLOODY good at it,
    A good API will make or break a PaaS/IaaS house so build the foundation well. and make it Restful

    Companies would kill for a community of tool building self sustaining contributors driving adoption of their product by selling yours (look what itś done for AWS)

    Itĺl be the best investment you make this week

  • Pete Otaqui commented
    September 11, 2018 19:23

    I've written up some thoughts on exactly how the current API would look if it was more RESTful:

    http://otaqui.com/blog/1651/digital-ocean-should-fix-their-api-heres-how/

  • Moisey Uretsky commented
    September 11, 2018 19:23

    Had a few requests for an update on the API including some on twitter so wanted to give everyone an update =]

    We are in the process of beginning the initial spec for our v2.0 API. We will be releasing this most likely on github to get comments from our customers well before we begin writing any code. This way we can work in as much feedback from our customers as possible without needing to rewrite anything and instead get everyone involved from the planning stage.

    We will be looking to support an additional method of Auth with the new API though it hasn't yet been determined which, in order to allow developers to easier create apps and integrations.

    You should see the first announcements regarding this around mid to late September as we will be in the process of on-boarding a few more engineers which will also be heavily involved in this project.

    Thanks!

  • Yury Lytvynenko commented
    September 11, 2018 19:23

    Vote for that. Destroying things via GET is very risky and can easily lead to the data loss.

  • Ionut Botizan commented
    September 11, 2018 19:23

    I agree that there's plenty of room for a better API, but I don't agree with the "last but not least" point.
    If you wouldn't have the predefined sizes and their IDs, you'd have to either allow the user to enter an arbitrary value or hardcode the available sizes in your application and let users choose one of those. None of those are ok because users will often enter some wrong values and, if you hardcode the available sizes, you'll have to update your app whenever a new size is introduced or one is removed.
    Just think of resizing as changing your pricing plan.

  • Aleksey Martynov commented
    September 11, 2018 19:23

    Voted up. Was surprised when saw that droplet destroy executed via HTTP GET!

  • Ricardo Obregón commented
    September 11, 2018 19:23

    It would be great that new API includes more info regarding the Droplets (IP, Bandwidth used, SSH Keys per droplet, and that kind of complementary info)

  • Moisey Uretsky commented
    September 11, 2018 19:23

    Agreed =]

  • Matt Walston commented
    September 11, 2018 19:23

    Awesome news. I know it is a big task, but consider eating your own dog food.

    In the long run, an SOA approach where the manager interacts with the API will be more maintainable and allow for all functionality to be easily exposed.

  • Moisey Uretsky commented
    September 11, 2018 19:23

    It's a big update so it will take about 2 months to get it completed.

  • Anonymous commented
    September 11, 2018 19:23

    Any updates about that?

  • Moisey Uretsky commented
    September 11, 2018 19:23

    Yup - we rolled out the first API as a simple quick way to get started because customers had requested it.

    Now that a lot of people are using it, it's time to roll-out v2 =]

  • Josh Frye commented
    September 11, 2018 19:23

    This could actually be done very quickly (esp in Rails)

    Example:

    match 'api/v2/droplets' => 'api/v2/droplets#create', :via => :post
    match 'api/v2/droplets/:id' => 'api/v2/droplets#show', :via => :get
    match 'api/v2/droplets/:id' => 'api/v2/droplets#update', :via => :put

    Then just create api/v2 directories in app/controllers like so:

    class Api::V2::DropletsController < ApplicationController
    end

    Can't wait for a versioned, verbed, restful API ;)

  • Álvaro Justen commented
    September 11, 2018 19:23

    Nice, Moisey! I'm waiting for it to start working on a Python library. :)

  • Moisey Uretsky commented
    September 11, 2018 19:23

    The adoption by the user base of the API is actually what drove the push for us to get started on this sooner.

    The current API will remain either as v1 or v0 and a new Restful API will be deployed.

  • Roland Moriz commented
    September 11, 2018 19:23

    +1

    With more and more 3rd party clients this will become harder to fix later, so better to clarify this soon. Thanks!

    Roland

    Author of:
    https://github.com/rmoriz/digital_ocean
    https://github.com/rmoriz/knife-digital_ocean

  • Álvaro Justen commented
    September 11, 2018 19:23