CODEWITHSUNDEEP
apihttprest
Andreas
Andreas

Reputation: 240

Modelling actions in REST

I'm making a REST interface to a management system (let's call this system A) for network equipment and I have everything working. A fetches the equipment information from another backend system (let's call this system B) and index it in a database and then whenever a client asks for the information over the REST interface it returns it as JSON.

However sometimes a client needs to forcefully make A refresh some equipment information by requesting it from B (without the client being involved besides asking A to refresh it). Refreshing the information for a single node takes several seconds so the information should probably not be returned in the same request as in which it is requested. Currently we've modeled this as that you create a job of a "refresh information" type using POST /jobs with some data. But this feels very over engineered and we'd much rather want something like POST /equipment/<id>/refresh but this feels to go against the "REST way"?

Is there any other solution to this than the one mentioned with jobs above but still follow the "REST way"?

Upvotes: 1

Views: 179

Answers (2)

Timothy Shields
Timothy Shields

Reputation: 79631

I would use GET /equipment/<id>?since=<timestamp>, where the since parameter is optional. Semantically this means:

  • Get the equipment with the given id as of whenever it happened to be last refreshed (when timestamp not given), or
  • Get the equipment with the given id refreshed no earlier than the given timestamp

Each equipment in your system would have a last_refreshed timestamp. The GET with the since=<timestamp> parameter would refresh the equipment if last_refreshed < since and then return the equipment.

A user of your service could then say GET /equipment/123?since=<15 minutes ago> and be sure they're always getting info that's no older than 15 minutes. GET /equipment/123?since=<now> means "force a refresh."

Upvotes: 1

Deividi Cavarzan
Deividi Cavarzan

Reputation: 10110

Keep in mind that POST in Rest services means that you will create some object.

To refresh one object, or update, it's recommended the PUT method.

Like um CRUD, when you have Create, Read, Update, and Delete, in REST will be POST, GET, PUT, DELETE (in order).

Maybe in your case the best URL for this is a PUT to /equipment/<id>.

URLs:

POST to /equipment/ : Create equipment

GET to /equipment/<id>: Read equipment with id <id>

PUT to /equipment/<id>: Update equipment with id <id>

DELETE to /equipment/<id>: Delete the equipment with id <id>

I hope that solve you doubt.

Anyway, a good reference it's the Apigee ebooks

Upvotes: 0

Related Questions