Search code examples
httprest

Http/REST method for starting a service

I want to design a REST API to start a database. I can't find a suitable http method (aka verb).

I currently consider:

START /databases/mysampledatabase

I've browsed through a few RFCs, but then I thought someone here might point me to a de-facto standard verb.

Methods I've discarded (before I got tired of looking):

RFC 2616 OPTIONS GET HEAD POST PUT DELETE TRACE CONNECT

RFC 2518 PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK

RFC 3253 REPORT CHECKOUT CHECKIN UNCHECKOUT MKWORKSPACE UPDATE LABEL MERGE BASELINE-CONTROL MKACTIVITY

Solution

  • 2024 edit

    My definition what what I think is REST is and isn't has shifted quite a bit since 2013, so I don't fully stand behind this answer anymore.

    REST != CRUD, and other aspects of your API (such as good use of URLs and discoverability of endpoints) is a far more important quality for something to be really REST.

    But of course the real question OP probably wanted to know was not "is this RESTful" which would spark endless debate anyway, but the more important question: "What is a good API design for representing starting a service".

    While the 'status' of the service could be expressed as a state on a resource, which could be modifyable with PUT or PATCH, simply using POST and an RPC-like call is probably fine. Don't overthink it. One of the nice things of plain HTTP apis is that you have a lot of tools available to you, and even if most of your API is modeled as a CRUD, it's totally fine to have some exceptions. It's not going to break HTTP clients or people's brains.

    Original answer

    There's a bunch of thinking flaws here.. first off, the additional HTTP verbs (aside from the CRUD ones) should be considered not-restful.

    So there's two ways I can interpret this question, and I have an answer for both:

    1. What's the most appropriate HTTP method for starting a service

    There's nothing quite like what you need, and I would advise simply using POST.

    2. What's a good RESTful way to start a service

    First, you should not see 'starting the service' as the action. It's easier to think of the 'status' (being started or stopped) as the resource you are changing, and PUT to update the resource.

    So in this case, each service should have a unique uri. A GET on that uri could return something like :

    { "status" : "stopped" }

    You just change 'stopped' to 'started', PUT the new resource.. and then the service could automatically begin running.

    I wonder how useful this is though.. I'm not a REST zealot, and I think a simple POST is the best way to go.