6

We have an application that is split into two parts:

  1. Admin - Where data is changed
  2. Public - Where data is read

I'm looking at creating a REST API to provide this functionality. It's very easy to see how CRUD operations can be represented but I am not sure about specific operations (commands) on an individual resource. For example to "Publish" a Project we send a "PublishCommand". We don't PUT the full Project back to the server with its Published property set to true.

On a similar note, I am a little confused at how we should represent more advanced query operations on resources without being classed as a RPC type service.

Below I've listed the URI templates for my Project resource. Am I on the right track for creating a truly RESTful API?

ADMIN API
---------

// Project Resources
GET /projects -- get all projects
POST /projects -- create a new project

// Project Resource
GET /projects/10 -- get project with id 10
PUT /projects/10 -- update project with id 10
DELETE /projects/10 -- delete project with id 10

// Project Resource Operations
POST: /projects/10/publish -- publish project with id 10
POST: /projects/10/unpublish -- unpublish project with id 10
POST: /projects/10/setposition/2 -- move to position 2 in projects list

// Project Sub resources (identity is local to project)
POST: /projects/10/media -- adds media to project with id 10
PUT: /projects/10/media/5 -- updates media id 5 for project id 10
DELETE: /projects/10/media/5 -- deletes media id 5 from project id 10

PUBLIC API
----------

GET: /projects -- gets all projects (with default limit e.g. first 10)
GET: /projects?skip=10&take=10 -- gets projects 11 to 20
GET: /projects/tagged/rest OR /taggedprojects/rest -- gets projects tagged with "REST"
GET: /projects?orderbydesc=publishdate OR /latestprojects -- gets latest projects

GET: /projects/10 -- gets project with id 10

2 Answers 2

5

I don't think that REST is intended to only represent CRUD operations. Your interface looks fine to me, and I believe you're on the right track.

There's a talk online about DDD and REST: RESTful SOA or Domain-Driven Design - A Compromise? by Vaughn Vernon.

Update to include a comment I made below:

You can query yor read model using GET. To mutate your domain you can PUT or POST to resources that represent commands. This would provide the richness of a domain model beyond CRUD and still use the inherent semantics of HTTP.

10
  • Will watch this. But remember, using HTTP verbs for conveying action is part of REST martinfowler.com/articles/richardsonMaturityModel.html
    – Aliostad
    Commented Jul 18, 2012 at 14:03
  • Thanks Dennis. This is precisely my concern - I shouldn't have to compromise the the richness of my domain model just so I can provide a RESTful API to talk to it.
    – Ben Foster
    Commented Jul 18, 2012 at 14:06
  • You can request yor queries using GET, and PUT or POST to resources that represent commands. This would provide the richness of a domain model beyond CRUD and still use the inherent semantics of HTTP. But I know that some people don't share this opinion. Commented Jul 18, 2012 at 14:12
  • 2
    @Aliostad I think he is conveying the actions correctly as he is creating projects using POST. Publish / Unpublish are operations / commands being started / executed by the "service" so POST is correct here also and I think its more explicit then doing a PUT for a project where the published property is set to true/false for example. Commented Jul 18, 2012 at 14:13
  • 2
    @BenFoster Constraining your REST interface to domain concepts is far too limiting. You need the ability to create new resources that do not map directly to the domain to overcome the limitations of only having a limited set of HTTP methods. Commented Jul 18, 2012 at 17:54
2

If you look at publishing as a resource, then you can use CRUD (POST/GET/PUT/DELETE):

  • POST to create a publish, passing project id
  • DELETE to unpublish
  • GET to retrieve

This does not mean that the process has to be associated with physical creation of records in database. It is just the resource-based approach which is important.

3
  • so we POST to /publishedprojects? What about those operations that don't really map at all to resources, such as the "Move" command.
    – Ben Foster
    Commented Jul 18, 2012 at 13:27
  • Still you need to think of it as a resource if you are fully abiding with REST. martinfowler.com/articles/richardsonMaturityModel.html
    – Aliostad
    Commented Jul 18, 2012 at 14:34
  • 1
    I don't see how this is possible for every operation that occurs within a domain as some operations do not map to a resource (like the "Move" example).
    – Ben Foster
    Commented Jul 18, 2012 at 14:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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