Thanks for the feedback.
We’ll discuss on our next call but I tend to fall in your camp that I think the header approach adds a level of complexity to the client work that could provide a potential obstacle to more jr devs.
I’ll incorporate your suggestion of including the version info in the payload.
···
On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rluk@dimagi.com wrote:
Hey team,
Thanks for the additional comments.
Just to clarify, I believe I misinterpreted the use of the word ‘header’. If we’re talking URL vs HTTP Header, then my preference goes against using the HTTP header. Using such headers will make it unnecessarily difficult for some clients to access this resource, and that kind of practical win is more important for our target audience than REST ideology.
What I would like, additionally, is to have that version information accessible in the payload somewhere, so that parsing can be done correctly without requiring the URL endpoint. But we could do this in addition to putting the version in the URL, if we so choose.
The important thing that both Cory and I are trying to get at is that version updates should not break pre-existing functional consumers unless it is absolutely necessary. If we agree on the contract that pre-existing endpoints remain available even as new ones are implemented, if possible, that solution would also work well for me.
Cheers,
Rowena
–
On Sat, Nov 3, 2012 at 10:23 AM, Cory Zue czue@dimagi.com wrote:
Long time lurker, first time contributer…
Just wanted to echo Justin’s preference against putting version info in the headers. It seems pretty obscure, much easier to mess up, and excludes many clients.
If the API is providing access to information I think the most important contract is that you don’t ever break any functional consumer. So once version one is accessible via a particular endpoint that needs to be serving that api/version for all time. It seems less than ideal to expect consumers to fail gracefully when the api changes, and also less than ideal to make every consumer implement logic that first checks the version and has failover logic if it doesn’t speak that version.
To me the simplest way to address this is to explicitly have the version in every url. If consumers want to change versions they have to change the url they hit, but that’s fine because they also have to change their business logic to work with the new version’s specification.
Note: take my opinion with a grain of salt since (1) i’m not closely involved in the planning and (2) i’m not particularly versed in api standards. This is just my opinion as an api developer/consumer.
Cory
On Sat, Nov 3, 2012 at 3:22 AM, Fyfe, Justin justin.fyfe1@mohawkcollege.ca wrote:
Hi All,
Read the document and made some comments inline (sorry for not sending this out sooner I realize this response got lost in my plethora of open windows).
Overall I think we have something that is a great starting point, and I can’t wait to start formalizing the documentation in the coming few months. I echo Rowena’s
sentiments about JSON/XML, my preference is the XML stack (XML/XSD/XSLT) but as a transport, JSON works well. It really depends on how the clients will be accessing the API.
I have had some experience with versioning API’s and it doesn’t matter which way you choose (URL, Header or in the message body) so long as the potential clients
are able to produce/read the version attributes. I know that in the development of HL7 FHIR they were discussing how to format requests which was a very similar topic (i.e. whether to use “accept: text/xml” and “accept: application/json” vs “/resource.xml”
and “/resource.json”). They chose to support the URL format even though it is not ideal. From what I remember (I don’t want to dig through the listserv
J), the major discussion points were:
Although headers are the appropriate way to address resource modifications, some clients cannot easily access/modify the HTTP headers for a response/request
(such as native Javascript in a web browser). Using HTTP headers may exclude these clients from consuming this data
Headers are the appropriate “RESTful” way of leveraging the transport (actually, I learned that true REST should never be versioned nor should resources
have formats/resource endpoints, rather this should be discovered at runtime, which I don’t fully understand the benefits of)
Modification of the resource URL is misleading, resources are supposed to point to something. To add something to the url which adds no meaning or
doesn’t modify a resource isn’t really proper. For example, /v1/resources/123.xml may actually be logically equal to /v2/resources/123.json since they may point to the same data. Ideally these two resources should have the same URL.
Either way is fine technically, again the style you use will depend on the intended consumers of this API.
Cheers
-Justin
From: Rowena Luk [mailto:rluk@dimagi.com]
Sent: November-02-12 4:22 PM
To: facility-registry@googlegroups.com
Cc: Rowena Luk; Fyfe, Justin; Kelly Keisling (NH); Eduardo Jezierski; Bob Jolliffe
Subject: Re: Updates on API
Hi Matt,
Thanks for the update! The API doc is so much easier to read now, and I appreciate the steps forward on the identifier issue.
re: xml vs json/geojson: I have a slight preference for json/geojson, but don’t feel strongly.
re: version in the header vs url: I would argue to maintain this information in the header. I dislike the idea of breaking backwards compatibility as the API version changes, particularly between a 1.0 and 1.1 release. I imagine the majority
of time the identified resource will not change, even if a few details of its representation changes, so maintaining consistent URI endpoints would be more consistent with standard RESTful architecture.
re: form definitions: I like the work Bob outlined here: https://github.com/bobjolliffe/facility_reference and the minimal set of features he identified. Is there a focused
debate around adding or remove specific fields?
Talk to you all soon,
Rowena
On Thu, Nov 1, 2012 at 10:06 PM, Matt Berg mlberg@gmail.com wrote:
Hi Rowena and Justin,
I just wanted to provide you a quick update on the API work.
We’re continuing to work on this doc v0.9.
https://docs.google.com/document/d/1_tVmFOO5uwR_pa-QqIz8m0ero77oqdF3a1eUOFDr1x8/edit
The two sections to focus on our Core features and the API endpoints section.
Today we reviewed the overall document and made progress on:
- Identifiers both internal GUID and external (a lot to discuss)
Next steps are:
- discuss the facility properties (do we want to have any form definitions?)
- reviewing the API queries
- Continue to go through the core elements and add what’s missing. If you can make any suggestions that would be great.
- figure out representation. XML vs. Georss. json vs geojson? Strong opinions all around
A couple of things we debated where we would love your opinion.
- versioning - do we include the version number in the url or via a header?
- representation debate (see above)
If you could go through this and provide feedback that would be wonderful. We’re hoping to setup another call to continue to work on this early next week.
Bob/Ed - please jump in if I forgot anything.
Thanks,
Matt
–
This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message. If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited. If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.
–