Updates on API

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 :slight_smile:

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

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 :slight_smile:

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

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:

···

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 :slight_smile:

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

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 :slight_smile:

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.

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 :slight_smile:

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.

Rowena and Cory,

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.

Thanks,

Matt

···

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 :slight_smile:

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.

Hi,

I would like to differentiate first on what are we trying to version??.

  • the resource

  • the representation

  • something else??

Each of these have been dealt with in different ways.

  • The resource can be versioned by putting ‘version’ as a property. This means that if you have properties added or removed from the resource, then the client can know what fields to expect

  • The representation on the other hand could also be versioned separately. This is what you’d normally expect in web-speak as “content negotiation”. using Accept header and mimetypes suggest that even if I had a special JSON representation, I can have v2 of that JSON representation without affecting all the other resources or representation of other resources. This allows flexibility that makes the web so awesome! There is also a mime-type version that can have multiple version of the same representation type. You could also call the versions by separate mime-types e.g. application/my2+xml

  • Something else versioning commonly chooses versioning end-points. This has been a common-trend because we might start offering another type of end-point fairly soon. e.g. websockets might be a replacement for REST-style endpoints and hence v2 can be used to refer to endpoints that are websockets.

So if we were versioning the whole API together, I’d use the URLs, but still allow resources and representations to evolve at their pace.

This I think makes better, more flexible and web-ways to do versioning

···

Regards,
Saptarshi PURKAYASTHA
My Tech Blog: http://sunnytalkstech.blogspot.com
You Live by CHOICE, Not by CHANCE

On Monday, November 5, 2012 9:39:10 PM UTC+1, mlberg wrote:

Rowena and Cory,

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.

Thanks,

Matt

On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rl...@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 cz...@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...@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:rl...@dimagi.com]
Sent: November-02-12 4:22 PM
To: facility...@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 mlb...@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 :slight_smile:

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.

Hi all

Good discussion. I am now going to risk popularity, brownie points etc by disagreeing a little over this versioning business.

I believe the api version info (and with a nod to Rowena and Saptarshi, we do need to unpack exactly what we mean by that) has no place in the url. This is certainly not because of any REST zealotry. I am not really too fond of json (at least for data exchange and processing) so I think that automatically disqualifies me as one of those :slight_smile:

The way I see it, unless you have full control of all the servers and all the clients, managing such URLs over time can become something of an ugly pain. Imagine you have many clients out there such as drupal mashup sites, HMIS instances etc all with many links to urls like http://facilityreg/api/v1.0/something/bobs_clinic_id. A soon as you upgrade the api “version” on the facility registry server all of the clients are broken. Keeping all of these urls in synch is difficult proposition.

So it is certainly much more robust to leave the version info out of the url.

And having sensible defaults whereby if the client does not specify the mimetype in the Accept header it will always get the latest rendition of the facility. Which in xml terms is easy enough to specify using a combination of namespace (for major) and version attributes (for minor changes) .

Now if a client does specify that it accepts version 1.0 in the mimetype and the server is actually providing v5.4 we would need to be clear about the required semantics of compliant servers.

I think we are exaggerating a bit the difficulty of client software adding these request headers. Sure its a slight step up but I imagine we can and will provide some simple examples in javascript, PHP etc.

Justin also raises the related but slightly different question of returning json, vs html vs xml on the basis of the url or an the basis of the Accept header.

I need to check what we do exactly in dhis2 web api, but I think a desirable behaviour is to

(i) return a default (html) rendition for a facility where there is no clue via extension or accept header

(ii) if the extension is present in the url (.xml, .json etc) use that

(iii) if the accept header is present then this trumps (ii) so use that. This can be quite important when you consider that there might be different xml renditions. For example our facility registry xml or an xform or something else. “Content-negotiation” using the url is just too limiting here.

Bob

···

On 5 November 2012 22:13, Saptarshi Purkayastha sunbiz@gmail.com wrote:

Hi,

I would like to differentiate first on what are we trying to version??.

  • the resource
  • the representation
  • something else??

Each of these have been dealt with in different ways.

  • The resource can be versioned by putting ‘version’ as a property. This means that if you have properties added or removed from the resource, then the client can know what fields to expect
  • The representation on the other hand could also be versioned separately. This is what you’d normally expect in web-speak as “content negotiation”. using Accept header and mimetypes suggest that even if I had a special JSON representation, I can have v2 of that JSON representation without affecting all the other resources or representation of other resources. This allows flexibility that makes the web so awesome! There is also a mime-type version that can have multiple version of the same representation type. You could also call the versions by separate mime-types e.g. application/my2+xml
  • Something else versioning commonly chooses versioning end-points. This has been a common-trend because we might start offering another type of end-point fairly soon. e.g. websockets might be a replacement for REST-style endpoints and hence v2 can be used to refer to endpoints that are websockets.

So if we were versioning the whole API together, I’d use the URLs, but still allow resources and representations to evolve at their pace.

This I think makes better, more flexible and web-ways to do versioning


Regards,
Saptarshi PURKAYASTHA

My Tech Blog: http://sunnytalkstech.blogspot.com

You Live by CHOICE, Not by CHANCE

On Monday, November 5, 2012 9:39:10 PM UTC+1, mlberg wrote:

Rowena and Cory,

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.

Thanks,

Matt

On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rl...@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 cz...@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...@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:rl...@dimagi.com]

Sent: November-02-12 4:22 PM

To: facility...@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 mlb...@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 :slight_smile:

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.

I don’t have a fixed position on conneg vs separate resources, but I would point out that even if you have different URLs for different versions of the API (media type?), you can have a resource that links to all the available versions of the URL.

When consumers of the API start relying on the structure of URLs, it makes URL management more difficult and restricts any new provider of the API.

Cheers,

Chris

···

On 5 November 2012 22:13, Saptarshi Purkayastha sunbiz@gmail.com wrote:

Hi,

I would like to differentiate first on what are we trying to version??.

  • the resource
  • the representation
  • something else??

Each of these have been dealt with in different ways.

  • The resource can be versioned by putting ‘version’ as a property. This means that if you have properties added or removed from the resource, then the client can know what fields to expect
  • The representation on the other hand could also be versioned separately. This is what you’d normally expect in web-speak as “content negotiation”. using Accept header and mimetypes suggest that even if I had a special JSON representation, I can have v2 of that JSON representation without affecting all the other resources or representation of other resources. This allows flexibility that makes the web so awesome! There is also a mime-type version that can have multiple version of the same representation type. You could also call the versions by separate mime-types e.g. application/my2+xml
  • Something else versioning commonly chooses versioning end-points. This has been a common-trend because we might start offering another type of end-point fairly soon. e.g. websockets might be a replacement for REST-style endpoints and hence v2 can be used to refer to endpoints that are websockets.

So if we were versioning the whole API together, I’d use the URLs, but still allow resources and representations to evolve at their pace.

This I think makes better, more flexible and web-ways to do versioning


Regards,
Saptarshi PURKAYASTHA

My Tech Blog: http://sunnytalkstech.blogspot.com

You Live by CHOICE, Not by CHANCE

On Monday, November 5, 2012 9:39:10 PM UTC+1, mlberg wrote:

Rowena and Cory,

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.

Thanks,

Matt

On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rl...@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 cz...@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...@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:rl...@dimagi.com]

Sent: November-02-12 4:22 PM

To: facility...@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 mlb...@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 :slight_smile:

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.

Hey Bob,

···

The way I see it, unless you have full control of all the servers and all the clients, managing such URLs over time can become something of an ugly pain. Imagine you have many clients out there such as drupal mashup sites, HMIS instances etc all with many links to urls like http://facilityreg/api/v1.0/something/bobs_clinic_id. A soon as you upgrade the api “version” on the facility registry server all of the clients are broken. Keeping all of these urls in synch is difficult proposition.

So it is certainly much more robust to leave the version info out of the url.

I’m a bit confused by this. As soon as you change the format of the data coming down you’ve potentially broken all the clients. So you have to support all versions for all time (or very gracefully deprecate over a long period of time).

It seems odd having the same URL serving different data formats based on something magic in the headers. It also seems odd to have every consumer of the API implement logic to negotiate a “which version do I support” handshake, when such a thing can be easily maintained in the URL.

If you use a reasonable API library (for example, we use tastypie in django[1]) providing versioned resources at different url endpoints is trivial.

Maybe I’m just confused about what you’re proposing and if so I apologize, and maybe you can clarify with an example of how the API would change and how a consumer would deal with that.

Cory

[1] http://django-tastypie.readthedocs.org/en/latest/api.html

And having sensible defaults whereby if the client does not specify the mimetype in the Accept header it will always get the latest rendition of the facility. Which in xml terms is easy enough to specify using a combination of namespace (for major) and version attributes (for minor changes) .

Now if a client does specify that it accepts version 1.0 in the mimetype and the server is actually providing v5.4 we would need to be clear about the required semantics of compliant servers.

I think we are exaggerating a bit the difficulty of client software adding these request headers. Sure its a slight step up but I imagine we can and will provide some simple examples in javascript, PHP etc.

Justin also raises the related but slightly different question of returning json, vs html vs xml on the basis of the url or an the basis of the Accept header.

I need to check what we do exactly in dhis2 web api, but I think a desirable behaviour is to

(i) return a default (html) rendition for a facility where there is no clue via extension or accept header

(ii) if the extension is present in the url (.xml, .json etc) use that

(iii) if the accept header is present then this trumps (ii) so use that. This can be quite important when you consider that there might be different xml renditions. For example our facility registry xml or an xform or something else. “Content-negotiation” using the url is just too limiting here.

Bob

On 5 November 2012 22:13, Saptarshi Purkayastha sunbiz@gmail.com wrote:

Hi,

I would like to differentiate first on what are we trying to version??.

  • the resource
  • the representation
  • something else??

Each of these have been dealt with in different ways.

  • The resource can be versioned by putting ‘version’ as a property. This means that if you have properties added or removed from the resource, then the client can know what fields to expect
  • The representation on the other hand could also be versioned separately. This is what you’d normally expect in web-speak as “content negotiation”. using Accept header and mimetypes suggest that even if I had a special JSON representation, I can have v2 of that JSON representation without affecting all the other resources or representation of other resources. This allows flexibility that makes the web so awesome! There is also a mime-type version that can have multiple version of the same representation type. You could also call the versions by separate mime-types e.g. application/my2+xml
  • Something else versioning commonly chooses versioning end-points. This has been a common-trend because we might start offering another type of end-point fairly soon. e.g. websockets might be a replacement for REST-style endpoints and hence v2 can be used to refer to endpoints that are websockets.

So if we were versioning the whole API together, I’d use the URLs, but still allow resources and representations to evolve at their pace.

This I think makes better, more flexible and web-ways to do versioning


Regards,
Saptarshi PURKAYASTHA

My Tech Blog: http://sunnytalkstech.blogspot.com

You Live by CHOICE, Not by CHANCE

On Monday, November 5, 2012 9:39:10 PM UTC+1, mlberg wrote:

Rowena and Cory,

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.

Thanks,

Matt

On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rl...@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 cz...@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...@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:rl...@dimagi.com]

Sent: November-02-12 4:22 PM

To: facility...@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 mlb...@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 :slight_smile:

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.

Hmm, I think actually the fundamental difference in how I’m thinking about this and how you all are (which maybe reflects why I should just stay out of this) is that I’ve been thinking from the perspective of designing a single web service, whereas I think the goal here is to define a set of standards that many different webapps should implement which has a different set of requirements.

So to that end I agree that you shouldn’t extract meaning by parsing out something in the url and assuming that is linked to the version and I also now understand the url management problem a bit better. I still like Chris’s idea of an index to a server’s own URLs as a way to automate the API discovery problem while still having each version at a different endpoint.

I suspect that for the practical case on the client side, 95% of the time you are only consuming this API against one server so most people could just bypass that logic in their app and point directly to the supported version.

Cory

···

On Tue, Nov 6, 2012 at 9:07 AM, Cory Zue czue@dimagi.com wrote:

Hey Bob,

On Tue, Nov 6, 2012 at 8:37 AM, Bob Jolliffe bobjolliffe@gmail.com wrote:

The way I see it, unless you have full control of all the servers and all the clients, managing such URLs over time can become something of an ugly pain. Imagine you have many clients out there such as drupal mashup sites, HMIS instances etc all with many links to urls like http://facilityreg/api/v1.0/something/bobs_clinic_id. A soon as you upgrade the api “version” on the facility registry server all of the clients are broken. Keeping all of these urls in synch is difficult proposition.

So it is certainly much more robust to leave the version info out of the url.

I’m a bit confused by this. As soon as you change the format of the data coming down you’ve potentially broken all the clients. So you have to support all versions for all time (or very gracefully deprecate over a long period of time).

It seems odd having the same URL serving different data formats based on something magic in the headers. It also seems odd to have every consumer of the API implement logic to negotiate a “which version do I support” handshake, when such a thing can be easily maintained in the URL.

If you use a reasonable API library (for example, we use tastypie in django[1]) providing versioned resources at different url endpoints is trivial.

Maybe I’m just confused about what you’re proposing and if so I apologize, and maybe you can clarify with an example of how the API would change and how a consumer would deal with that.

Cory

[1] http://django-tastypie.readthedocs.org/en/latest/api.html

And having sensible defaults whereby if the client does not specify the mimetype in the Accept header it will always get the latest rendition of the facility. Which in xml terms is easy enough to specify using a combination of namespace (for major) and version attributes (for minor changes) .

Now if a client does specify that it accepts version 1.0 in the mimetype and the server is actually providing v5.4 we would need to be clear about the required semantics of compliant servers.

I think we are exaggerating a bit the difficulty of client software adding these request headers. Sure its a slight step up but I imagine we can and will provide some simple examples in javascript, PHP etc.

Justin also raises the related but slightly different question of returning json, vs html vs xml on the basis of the url or an the basis of the Accept header.

I need to check what we do exactly in dhis2 web api, but I think a desirable behaviour is to

(i) return a default (html) rendition for a facility where there is no clue via extension or accept header

(ii) if the extension is present in the url (.xml, .json etc) use that

(iii) if the accept header is present then this trumps (ii) so use that. This can be quite important when you consider that there might be different xml renditions. For example our facility registry xml or an xform or something else. “Content-negotiation” using the url is just too limiting here.

Bob

On 5 November 2012 22:13, Saptarshi Purkayastha sunbiz@gmail.com wrote:

Hi,

I would like to differentiate first on what are we trying to version??.

  • the resource
  • the representation
  • something else??

Each of these have been dealt with in different ways.

  • The resource can be versioned by putting ‘version’ as a property. This means that if you have properties added or removed from the resource, then the client can know what fields to expect
  • The representation on the other hand could also be versioned separately. This is what you’d normally expect in web-speak as “content negotiation”. using Accept header and mimetypes suggest that even if I had a special JSON representation, I can have v2 of that JSON representation without affecting all the other resources or representation of other resources. This allows flexibility that makes the web so awesome! There is also a mime-type version that can have multiple version of the same representation type. You could also call the versions by separate mime-types e.g. application/my2+xml
  • Something else versioning commonly chooses versioning end-points. This has been a common-trend because we might start offering another type of end-point fairly soon. e.g. websockets might be a replacement for REST-style endpoints and hence v2 can be used to refer to endpoints that are websockets.

So if we were versioning the whole API together, I’d use the URLs, but still allow resources and representations to evolve at their pace.

This I think makes better, more flexible and web-ways to do versioning


Regards,
Saptarshi PURKAYASTHA

My Tech Blog: http://sunnytalkstech.blogspot.com

You Live by CHOICE, Not by CHANCE

On Monday, November 5, 2012 9:39:10 PM UTC+1, mlberg wrote:

Rowena and Cory,

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.

Thanks,

Matt

On Mon, Nov 5, 2012 at 2:31 PM, Rowena Luk rl...@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 cz...@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...@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:rl...@dimagi.com]

Sent: November-02-12 4:22 PM

To: facility...@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 mlb...@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 :slight_smile:

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.

Hi everyone,

I’ve been lurking here for a while because UNICEF is hoping to adopt this facility API for several upcoming mhealth projects.

This is a really interesting discussion, and I have a couple of thoughts to add

clients with traffic going through proxies (many mobile 3g dongle connections, certain vsat connections, etc) may have non-standard headers stripped from their traffic, so something like ‘X-API-Version:2’ might not make it through. we’d probably have to ‘smuggle’ the api version in another header to increase the chances of it making the journey to proxied clients with something like ‘Server: ourFacilityAPI/2.0’ or ‘User-Agent: ourFacilityAPI/2.0’

another option is to combine these approaches by sending the api version in the header and also as a uri component. if there is no version uri component provided, then the service should default to the current, most recent api version (and every request should always include the version in a header as well). so, if a client includes the version uri component, we never violate the ‘principle of least astonishment’ by changing the behavior of the same resource call – yet at the same time, the ‘clean’ uri (without version) will always behave as the most recent version. this way the choice is left to the client and we do not have to impose a workflow around updating and maintenance. if a client wishes to wait to update their api implementation, they are free to do so by continuing to access the older api version. if another client wishes to stay on the bleeding edge, they are free to update their implementation as the versionless endpoint changes.

of course we would not want to support, say, api version 2 when we have just rolled out version 12, so there would need to be a deprecation schedule where past versions continue to operate normally for a certain period. after that period, the old endpoints could return 302 Found as a way to notify the caller of the newer endpoint. and then after a bit longer, the old endpoints could return 301 Moved Permanently once the old endpoint is no longer available.

cheers

evan

Hi

···

On 6 November 2012 14:55, evan wheeler evanmwheeler@gmail.com wrote:

Hi everyone,

I’ve been lurking here for a while because UNICEF is hoping to adopt this facility API for several upcoming mhealth projects.

This is a really interesting discussion, and I have a couple of thoughts to add

clients with traffic going through proxies (many mobile 3g dongle connections, certain vsat connections, etc) may have non-standard headers stripped from their traffic, so something like ‘X-API-Version:2’ might not make it through. we’d probably have to ‘smuggle’ the api version in another header to increase the chances of it making the journey to proxied clients with something like ‘Server: ourFacilityAPI/2.0’ or ‘User-Agent: ourFacilityAPI/2.0’

Yes. I was thinking in terms of the version number as part of the mimetype of the Accept header. Though of course I do accept that this is one interpretation of what we might understand as version.

another option is to combine these approaches by sending the api version in the header and also as a uri component. if there is no version uri component provided, then the service should default to the current, most recent api version (and every request should always include the version in a header as well). so, if a client includes the version uri component, we never violate the ‘principle of least astonishment’ by changing the behavior of the same resource call – yet at the same time, the ‘clean’ uri (without version) will always behave as the most recent version. this way the choice is left to the client and we do not have to impose a workflow around updating and maintenance. if a client wishes to wait to update their api implementation, they are free to do so by continuing to access the older api version. if another client wishes to stay on the bleeding edge, they are free to update their implementation as the versionless endpoint changes.

of course we would not want to support, say, api version 2 when we have just rolled out version 12, so there would need to be a deprecation schedule where past versions continue to operate normally for a certain period. after that period, the old endpoints could return 302 Found as a way to notify the caller of the newer endpoint. and then after a bit longer, the old endpoints could return 301 Moved Permanently once the old endpoint is no longer available.

Its interesting to go bacjk to the motivating discussion last week which got this conversation started. Resource mapper supports the notion of collections, or what in this context would be a registry of facility registries. We (DHIS folk) think this is a pretty cool RM feature, but not really something which can reasonably be required of any compliant facility registry. We all agree on this, but then it emerged last week that we had a problem with URLs. Specifically things like:

http://facilities.moh.gov.rw/api/1.0/Collections/345/facilities/50181.xml

If we agree that we are only concerned in standardizing the “facilities/50181.xml” part we are left with a slightly ugly problem for RM who still want to syupport their multiple Collections. You could end up with a url a bit like this:

http://facilities.moh.gov.rw/Collections/345/api/1.0/facilities/50181.xml

And of course if RM (or DHIS or anything else) chose to version their own web api in a similar way it starts to get even more unwieldy; eg

http://facilities.moh.gov.rw/api/5.6/Collections/345/api/1.0/facilities/50181.xml

So we concluded that “api” doesn’t add any value and shouldn’t be mandated. But the numbers still get in the way. And if we find ourselves having to mandate Collections as part of the api in order to make neater URLs then that would not be a good motivation.

We much prefer the following url:

http://facilities.moh.gov.rw/Collections/345/facilities/50181.xml

Where desired version information of the content type could be (optionally) placed by the client in the Accept mimetype header.

Cheers

Bob

cheers

evan

It’s worth considering that direct clients of the API aren’t the only potentially interested parties in our versioning decision. Other services that wish to link to a facilities registry need to know what URLs to use.

If versioning is part of the URL, that will mean that other services have to pick which version of the API they link their clients to - which may or may not be what we want. For example, if the Ugandan ministry of health wants to maintain a list of facilities, they couldn’t link to the conceptual facilities themselves, they would have to go through a particular API version and decide when to link through a new one.

Chris

···

On 6 November 2012 14:55, evan wheeler evanmwheeler@gmail.com wrote:

Hi everyone,

I’ve been lurking here for a while because UNICEF is hoping to adopt this facility API for several upcoming mhealth projects.

This is a really interesting discussion, and I have a couple of thoughts to add

clients with traffic going through proxies (many mobile 3g dongle connections, certain vsat connections, etc) may have non-standard headers stripped from their traffic, so something like ‘X-API-Version:2’ might not make it through. we’d probably have to ‘smuggle’ the api version in another header to increase the chances of it making the journey to proxied clients with something like ‘Server: ourFacilityAPI/2.0’ or ‘User-Agent: ourFacilityAPI/2.0’

Yes. I was thinking in terms of the version number as part of the mimetype of the Accept header. Though of course I do accept that this is one interpretation of what we might understand as version.

another option is to combine these approaches by sending the api version in the header and also as a uri component. if there is no version uri component provided, then the service should default to the current, most recent api version (and every request should always include the version in a header as well). so, if a client includes the version uri component, we never violate the ‘principle of least astonishment’ by changing the behavior of the same resource call – yet at the same time, the ‘clean’ uri (without version) will always behave as the most recent version. this way the choice is left to the client and we do not have to impose a workflow around updating and maintenance. if a client wishes to wait to update their api implementation, they are free to do so by continuing to access the older api version. if another client wishes to stay on the bleeding edge, they are free to update their implementation as the versionless endpoint changes.

of course we would not want to support, say, api version 2 when we have just rolled out version 12, so there would need to be a deprecation schedule where past versions continue to operate normally for a certain period. after that period, the old endpoints could return 302 Found as a way to notify the caller of the newer endpoint. and then after a bit longer, the old endpoints could return 301 Moved Permanently once the old endpoint is no longer available.

Its interesting to go bacjk to the motivating discussion last week which got this conversation started. Resource mapper supports the notion of collections, or what in this context would be a registry of facility registries. We (DHIS folk) think this is a pretty cool RM feature, but not really something which can reasonably be required of any compliant facility registry. We all agree on this, but then it emerged last week that we had a problem with URLs. Specifically things like:

http://facilities.moh.gov.rw/api/1.0/Collections/345/facilities/50181.xml

If we agree that we are only concerned in standardizing the “facilities/50181.xml” part we are left with a slightly ugly problem for RM who still want to syupport their multiple Collections. You could end up with a url a bit like this:

http://facilities.moh.gov.rw/Collections/345/api/1.0/facilities/50181.xml

And of course if RM (or DHIS or anything else) chose to version their own web api in a similar way it starts to get even more unwieldy; eg

http://facilities.moh.gov.rw/api/5.6/Collections/345/api/1.0/facilities/50181.xml

So we concluded that “api” doesn’t add any value and shouldn’t be mandated. But the numbers still get in the way. And if we find ourselves having to mandate Collections as part of the api in order to make neater URLs then that would not be a good motivation.

We much prefer the following url:

http://facilities.moh.gov.rw/Collections/345/facilities/50181.xml

Where desired version information of the content type could be (optionally) placed by the client in the Accept mimetype header.

Cheers

Bob

cheers

evan