API convention for server-side "variables"

Question

I'm looking at an API scenario where you have an entity, like a phone call, which you can stop once and start once. I was thinking of modelling this as something like the following:

{
 start_time: null | date,
 end_time: null | date
}

However, I don't want the client to actually be able to set these fields freely. Rather, I want them to be able to send a request to this resource to start it, whereby the server puts the current time according to its own clock, and then to send a request to end, whereby the server does the same thing for the end_time field.

Which led me to wonder, is there an API convention specifying variables that can be used in request? For example, I could envisage an API specifying that a variable called "$now" represents the current time according to the API. Under this system, if at 2017年03月06日T01:55:42+00:00 (by the server's clock) you send ...

PUT /call/1/
{
 start_time: "$now",
 end_time: null
}

... you would see, in a subsequent get request:

GET /call/1/
{
 start_time: "2017-03-06T01:55:42+00:00",
 end_time: null
}

Does anyone know of a convention for specifying things like this - specifically, for outlining which variables of this sort are available to the client and what they mean? Is this a good way to go about things in a Resourceful (I won't say RESTful, because no hypermedia) API?

• Ewan: seems like a bad idea to me. is start_time a date or a string?
• Walfrat: "what they mean" : proper naming solve that. FOr a definition file like a WSDL, it is called WADL and there are tools on the web for that.
• Laiv: I don't want the client to actually be able to set these fields freely is not what you are suggesting just the opposite? I see It contradictory. What if there were $tomorrow or $in15minutes, etc... Would you allow client to decide when to start? What's the difference between that and "freely initialize the start_date?
• icirellik: Updating start and end time in different requests will cause some problems. How will you handle the scenario where a phone failed to write its end time and what does that mean to the application?

Answer 1

Is there a reason for sending the start_time|end_time elements from the client at all if the server is handling the times? I would probably do something like the following, although API design is a lot down to preference -

POST /call
 {caller_id: value, ...}

Send a request containing any call metadata (such as the src/dst numbers, etc) This would use current time as the call start and return a call reference / ID chosen by the server.

PUT /call/{ref}
 {ended: true}

Send an update with an ended: true element to signify the end of the call. The server can then apply the current time to its end_time field.

This is based on the API handling real time calls with no ability for the client to specify call start or end times. (i.e. the client sends one request as the call starts and another when it ends).

• Walfrat: or evven better : call/{ref}/start, call/{ref}/end, make the API more readable.
• USD Matt: With that you'd need to know the reference to start the call though. Makes sense to create a call and start it in one request. I did consider /call/{ref}/end although it seemed awkward to send an empty POST|PUT request to that, and using GET would break a fundamental API rule.
• Walfrat: yeah I might have be a bit fast on that :). I have already see search pages use POST operation with QUERY String in the URL not in the body, so user can share a link of his search. I don't see anything wrong with that.
• Andy: POST request with an empty body to /call/{id}/end is completely fine. I like it more than the PUT you mentioned in your answer, because having the PUT indicates you could end the call twice, which you, obviously, cannot.
• Laiv: Or DELETE if you considered a running call and Its resume to be different resources. Afterall, a running call is no longer available after its end.

Answer 2

Other answers to this post provide reasonable alternatives to maintaining value references in your API. They also illustrate the simple answer to your question:

No, there is no standard convention for specifying value references in JSON.

Anything that exists is someone's idea for how to solve a problem like yours. Some ideas may work better than others.

Without some metadata built into your API (e.g., WSDL, or something WCF can build for you), your only mechanism to convey the details of your solution to your problem is to document it yourself, which you may (or may not) incorporate into your API.

But no, there is no generally accepted convention for value references, or for documenting them in a standard way.

Answer 3

Does anyone know of a convention for specifying things like this - specifically, for outlining which variables of this sort are available to the client and what they mean?

Regardless the intentions beneath this question -and the usages for these variables-, consider turning these variables into resources too.¹

GET /env/variables HTTP 1.1 
...
HTTP 200 Ok
...
{ 
 "now":{
 "description":"Server's current date and time",
 "value":"2017-03-06T01:55:42+00:00",
 "time-zone":"UTC",
 "reference":"$now",
 "type": "Date"
 },
...
}

This way, we allow clients to be aware of them. However, how to digest the variables on both -client and server- sides is up to you.

Back to the OP' question and according with its example, -as @USD Matt has commented- if server-side handles the call's timmings, there's no need for the clients to know which variables come into play on the server-side and there's no need either for them to tell the server which variables to use.

Otherwise, there wouldn't be any difference between allowing arbitrary inputs and allowing specific variables as inputs. The client would be choosing the value for start-time anyways.

Note: Take in account that there could be 3 different start-times. The caller' start-time, the server' start-time and the start-time for whoever is on the other side of the wire.

---

^{1: The above representation is just for illustration. Feel free to implement the one that best serves your purposes.}