4

I am creating a REST API for a weigher (to be run on a Raspberry Pi, integrated into the weigher), and I was wondering if my ideas are RESTful and correct.

I have the resource "measurement" that you can use to fetch previously stored measurements, using an ID to get a specific one:

GET http://1.2.3.4/measurement/<id>

I was thinking to use ID 0 as "the current measurement", i.e. what the weigher is weighing at the moment of the call.

Would that be 'correct' ? Or should I use a different resource?

  • 3
    Just using the word Current would be more explicit and make it clearer whats available at that URI. – richzilla Apr 26 '17 at 8:16
  • @richzilla Thanks. It will probably be live but the idea is the same. – Bart Friederichs Apr 26 '17 at 8:52
6

REST doesn't care what spelling you use for your URI.

URI design considerations typically flow from the needs of human beings working with them, rather than those of the clients (which treat the identifiers as opaque data). The structure of the URI is primarily hierarchical, with conventions that separate the hierarchical data from the non-hierarchical data. But those guidelines are human convention, much like the rules around variable names in your coding standards.

/3fa527b4-1036-44b2-a7f3-7770d4b15beb

is a perfectly cromulent URI.

I was thinking to use ID 0 as "the current measurement", i.e. what the weigher is weighing at the moment of the call.

The semantics of that are perfectly reasonable. Fielding, in his thesis defining REST, wrote

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

... The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.

That's not a spelling I would recommend; however. It reeks of MagicNumber. To avoid misunderstandings by human readers, I would normally go with one of the other recommendations here: /measurements/live, /measurements/current, /measurements?asOf=now, etc.

As a manner of mechanics, if the current measurement has a permanent identifier as well, I would redirect requests from the current to the permanent.

GET /measurements/latest

302 See-Other
Location /measurements/12345

(again, in REST it is perfectly reasonable to have many resources that share the same representation, or share the same representation for the moment.)

1

No, thats absolutely wrong. It would mean that the ID 0 is not actually an identifier but rather some magical thing that might refer to something else every time you use it.

Instead, offer an option to sort your measurement index (/measurements) by time, most recent measurement first. If a caller wants to get the latest measurement they simply fetch the index and read the most recent one:

GET http://1.2.3.4/measurements

[
  {
    "value": 78.3,
    "measuredAt": "2017-04-16T10:15:10.0Z"
  },
  {
    "value": 78.4,
    "measuredAt": "2017-04-16T10:15:09.5Z"
  },   
  {
    "value": 78.3,
    "measuredAt": "2017-04-16T10:15:09.0Z"
  },
  {
    "value": 78.2,
    "measuredAt": "2017-04-16T10:15:08.5Z"
  },
  ... and so forth
]

pseudo code:
function getCurrentMeasurement()
  measurements = GET http://1.2.3.4/measurements | json
  return measurements[0]
  • And what about using /measurement/live, as suggested in the comments? The live measurement is supposed to be called each 0.5 seconds (to create a live monitor on a webpage), so making it two calls seems overdone. – Bart Friederichs Apr 26 '17 at 8:56
  • 1
    That is fine, too, as far as REST and HTTP are concerned. As a matter of taste i'd not do it though, because the sorted index can fulfill the requirement in one call (edited the answer) – marstato Apr 26 '17 at 9:17
  • 1
    @BartFriederichs BTW, if you want a live display, websockets seem like the better solution to me. Polling is always dirty. – marstato Apr 26 '17 at 9:22
  • agreed, but I want to keep it simple and versatile for now. The HTML client will be just an implementation. Others might want to call that live measurement on a button, or whatever they decide to implement and then a HTTP API call will be useful for them. – Bart Friederichs Apr 26 '17 at 9:25

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.