2

I want to add actions to my REST API that would move 'resources' between different 'stores'.

For instance, suppose my resources are normally accessed by the following URL:

/resources
/resources/{resourceId}

Now suppose I want to 'deactivate' some resource, i.e. conceptually move it to another sub-folder. The most straightforward way to allow this would be as followed.

  1. 'Deactivate' the resource, i.e. cause it to be unavailable under /resources. Conceptually, it 'moves' the object to the '/resources/deactivated/' subfolder:

    POST /resources/{resourceId}/deactivate   
    

    Or alternatively:

    POST /resources/deactivated/{resourceId}
    
  2. Get all the deactivated objects:

    GET /resources/deactivated      
    
  3. Reverse the 'deactivate' action, i.e. conceptually move the object from the '/resources/deactivated/' subfolder back to the main one ('/resources').

    Either

    POST /resources/{resourceId}/reactivate    
    

    Or

    POST /resources/deactivated/{resourceId}/restore     
    

    This API seems rather intuitive for me. But it seems to violate the 'prefer nouns' rules that I have seen in many best practices-articles on REST API: I use verbs and adjectives instead of nouns!

Note that I might have parameters for all the endpoints, e.g. GET /resources/deactivated?createdBefore=01022017

Are there any better alternatives for my REST API? I.e. more RESTful, but not less intuitive ones?

Good resources that I could find on the topic:

4 Answers 4

8

First of all, remember that REST stands for Representational State Transfer.

It is all about resources and their state. Operations such as activate, deactivate and move are all about replacing the current state of the resource with a new representation and you don't need verbs in the URL to express such operations.


For example, to replace a status of a resource, you can send a new representation of the resource in the payload of a PUT request:

PUT /api/resources/[id]/status HTTP/1.1
Host: example.org
Content-Type: application/json

{ "status" : "active" }

It can be understood as replace the status of the resource identified by [id] with the one sent in the request payload.


Then you could have the following to get the resources with a particular status:

GET /api/resources?status=active HTTP/1.1
Host: example.org
Accept: application/json

It can be understood as give me a representation of all resources with the status active.


To move a resource to another folder, for example, you could have:

PUT /api/resources/[id]/folder HTTP/1.1
Host: example.org
Content-Type: application/json

{ "target" : "draft" }

It can be understood as replace the folder of the resource identified by [id] with the one sent in the request payload.

7
  • 1
    I like your answer (voted) as it gives me a better understanding of the REST approach. Yet I don't think simply changing a 'status' attribute would be acceptable in my case, since 'GET /resources' should not return the deactivated ones.
    – Alexander
    Apr 12, 2017 at 8:10
  • 2
    @Alexander To get all resources you can request GET /api/resources. It will return the active and inactive ones. To filter the resources collection, you can use a query parameter like status. So GET /api/resources?status=active would return the active ones, while GET /api/resources?status=inactive would return the inactive ones. You could assume default values for your query parameters. If the status is ommited, assume that you want only the active ones. Apr 12, 2017 at 8:30
  • I disagree. 'GET /resources' should return all the objects, regardless of values of specific attributes, otherwise it is very confusing. But on the other hand, it should not return the 'deactivated' ones, which means it is not simply a regular attribute.
    – Alexander
    Apr 12, 2017 at 8:40
  • 1
    @Alexander Have a look at the GitHub API to list issues: GET /issues. The filter query parameter can be used to indicates which sorts of issues to return. If no value is provided, the assigned value is used as default. Apr 12, 2017 at 9:02
  • Thanks Cassio. Well, convinced. They are placing a star on a gist with 'PUT' as well. developer.github.com/v3/gists/#star-a-gist .
    – Alexander
    Apr 12, 2017 at 9:56
3

Is an active resource really that different than a deactivated resource? Consider just having a property that tracks activeness. You can always filter them out, such as

GET /things?active=true

You can alter just that property with a microPUT

PUT /things/{id}/active
false

If a thing and a deactivated-thing are conceptually different, it's reasonable to have two separate endpoints. I would move between them using

POST `/deactivated-things`
{
    "thing": "/things/12"
}

and

POST `/things`
{
    "deactivated-thing": "/deactivated-things/12"
}

You should try to avoid a path having multiple meanings. For example, don't do this:

/resources/{id}
/resources/deactivated/{id}

Don't overload the meaning of the path segment after /resources.

2

One thing you never see mentioned with REST:

Don't confuse REST with web app or pretty urls.

eg. when a user logs in to edit their account, you would show

www.example.com/home
www.example.com/account
www.example.com/profile

and not

// www.example.com/users/{id} ...
www.example.com/users/433563444335634443356344
www.example.com/users/433563444335634443356344/edit

I think this is where many devs get confused. REST is great for APIs, but in terms of web apps, it should be used as the internal API for form action endpoints or ajax, for example, but not necessarily as the pretty url.

1

Thanks Cassio for emphasizing the 'changing the object state' approach.

My own answer for completeness:

PATCH /resources/{resourceId} with body {"active":false}  -- deactivate a resource
PATCH /resources/{resourceId} with body {"active":true}  -- restore a resource
GET    /resources                        -- return all 'normal' resources
GET    /resources?includeInactive=true   -- return all resources including the deactivated ones
GET    /resources/{resourceId}           -- return the resource 

(The resources retrieved by 'GET' will contain the attribute 'active=true/false').

Seems like a classic case for PATCH: REST API PATCH or PUT

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.