How an RPC-style example would look modelled in a

Question

I have been reading around the web about REST for several days now and am struggling with the concept of HATEOAS.

I think I am struggling because I don't properly understand how to model data as resources and (state-transitioning?) links between resources. I believe my problem is that all my experience is OO and RPC and I am unused to thinking in a resource-centric manner.

The only way to get an understanding is to take an example from my world, say what I think that might look like modelled in a resource/link-centric manner and throw it out there to be shot down in flames. After the burn is complete I should at least have a better understanding of what I don't understand.

My (simplified) example is:

I am a contractor e.g. a plumber. I have a number of jobs assigned to me. I can search my jobs specifying simple paramaters such as a target date range. I can start any job assigned to me. When I start the job, I can optionally specify the time I started it or leave it blank if I am starting it now.

If I were implementing this in an RPC manner I might expose two methods to callers:

ListOfJobs GetJobs(search parameters)
StartJobResult StartJob(jobID, optional start datetime)

As you can see, I am thinking objects and operations.

If I were thinking resources and links, what might the resources be?

My guess is:

• Contractor: ~/contractor/plumbersareus ?
• JobSearch: ~/contractor/plumbersareus/searches/searchidentifier ?
• Job: ~/job/12345 ?
• Attendance: ~/job/12345/attendances/attendanceidentifier ?

Assuming any of the above is correct (and I doubt it is), what should "searchidentifier" and "attendanceidentifier" be? The former wouldn't have an identity in my RPC world; it would just be parameters. The latter would be identified by a DateTime.

What might the links be (ignoring links to self)?

• Contractor: ~/contractor/plumbersareus/searches ?
• JobSearch: ~/job/12345, ~/job/12346, etc ?
• Job: ~/job/12345/attendances ?
• Attendance: ?

Please accept my apologies if this a repeat question and close it down. (I couldn't find a repeat but I may have been searching with the incorrect terms.)

Answer 1

You may have read these two great books:

• REST in Practice

• Restful Web Services

Back to your questions. The more practical way of thinking or applying REST as the starting point (at least it works for me) is to think in the following ways:

1) Use only HTTP ‘GET/POST/PUT/DELETE’ as the way to model your domain ‘actions’ . Just like when you dealing with database, all your actions are mapped to CURD.

2) URI/URL is to identify resources only. Should never have any ‘actions’ in your URI.

3) The data exchanged should be in the body of the HTTP messages. Just to simplify the discussions, not getting into how to model the data itself

Here is what comes to my mind. I’m sure that there are better ways to model what you have but it should be around the same principles☺ E.g. how the URL patterns look like is all depending on your application domain and what makes sense between the client and the backend.

To model ‘get jobs’:

• HTTP: GET
• URL: ~/contractors/[plumberID]/jobs/

To model, job search:

• HTTP: GET
• URL: ~/jobs/?[some search params]/

To model assign the job to user:

• HTTP: PUT
• URL: ~/contractors/[plumberID]/assignments/[jobID]

There are some differences in using PUT vs POST, you can search around.

Hope this help.