Search code examples
restrestful-architectureapi-design

API routes that perform actions

So traditional API resources allow you to GET, PUT, PATCH, DELETE etc a resource.

/api/v1/user/$id

However what is the technical term for a route that performs an action and returns some response about the outcome of that action?

/api/v1/flushcache
Solution

  • One way is to just have a cache resource:

    /api/v1/cache

    Which would return some cache state for example application/vnd.company.cachestate+json:

    {
    "state": "active",
    "objectCount": 123
}

    Then you could PUT the same representation:

    {
    "state": "flushed"
}

    Which could return:

    {
    "state": "active",
    "objectCount": 0
}

    The point is, you have to first formulate the problem in the existing terminology. The terms used are always:

    • Resource (what you call 'Route'): An entity that has some business semantics
    • Representation: The actual message format used by a Resource. A Resource might support multiple representations!
    • Mime-Type: The formal description of a Representation (or multiple ones)

    So, again, there is usually no Resource that "does" something, more like, Resources represent some Business Entity, and the standard operations (GET, PUT, POST, DELETE, etc.) are mapped to some operations on that entity.