Putting version number in API calls.

[Karl Fogel]

Hey, all. For the OpenHMIS API [1] recently implemented by Dan Schultz, we decided to put the API version number in the services base in the URL -- see the "api/v3/" portion of these examples:

http://hmis.example.com/openhmis/api/v3/clients
http://hmis.example.com/openhmis/api/v3/clients/3637
http://hmis.example.com/openhmis/api/v3/enrollments
http://hmis.example.com/openhmis/api/v3/enrollments
http://hmis.example.com/openhmis/api/v3/enrollments/1729/contacts/35

etc. This way:

- "api/" makes it clear these URLs are RESTful API calls, and
- "v3/" makes it clear what version of the API is being called

We're planning something like the http://semver.org/ scheme for deciding when the API version number must be incremented (basically, on backwards-incompatible changes), of course.

I'd like to get others' thoughts on this general practice. Putting the API version in the URL like this seems to be fairly standard nowadays, at least with other APIs I've seen, but if there are arguments for or against it, in an HMIS API, this seems like the right forum to discuss it.

Unrelatedly, in response to Eric Jahn's recent post:

>Yes, I'm all in for an Fall NHSDC pow wow to come to some further
>consensus with the other vendors on where API functionality should go
>for a next version.  Improved auth, improved convenience methods and
>search, user administration, reporting, etc. seem like good
>candidates.  Not that each vendor would be asked to implement each
>new method, but that those methods are there for them, if the need
>arises.  Who else is in? -Eric

Would love to be there, yes, and will see if I can make it. If we can get Dan Schultz there, so much the better! But please note https://twitter.com/slifty/status/631853747170357248 which may mean Dan has different plans in October, we'll just have to see :-). (Congratulations, Dan!)

Best regards,
-Karl Fogel

[1] https://github.com/PCNI/OpenHMIS/blob/feature-compass_schema/docs/API.md

[Eric Jahn]

Karl, yes, we also want to follow that semver versioning with hmis-api.  I have to configure the anypoint documentation site to use that url scheme.  We'll continue to follow the major.minor.patch way they recommend, although I know it's common to just use whole numbers for APIs, but I think we still need that fine grained versioning. -Eric

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+u...@googlegroups.com.
To post to this group, send email to hmis...@googlegroups.com.
Visit this group at http://groups.google.com/group/hmis-api.
To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/87tws252o4.fsf%40red-bean.com.
For more options, visit https://groups.google.com/d/optout.

[Dan Schultz]

Eric remember it will break apps every time you change the url.

I highly suggest using only major updates for api url changes.  Fine grain is useful at the dev level, but at the url level the major version ends up being more practical

Best,

  Dan

To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/CANHzzoNFzn9X5kG8bf2Wfk5u_EMNz%3D15cnt-yYzg3FNLkW6ZVg%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--
Semt feom a mobil dvice. Please fotgive any typps.

[Eric Jahn]

Dan, makes sense, okay, major only for urls.

[Steve Conners]

Major versions in the url sounds good.

Steve

Steve Conners - Director, Systems
Pathways Community Network Institute     "...with you every step"

PO Box 450147
Atlanta, GA 31145-0147
[Office] 404.639.9933 x321   [Toll Free] 866.818.1032 x321   [Cell] 678.718.7264

www.pcni.org

 

 

To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/CANHzzoOx4%3DUCfbmesedRKsrhxka2Mgq0X7-xDGX7epPNn0J_qA%40mail.gmail.com.

[Karl Fogel]

Steve Conners <steve....@pcni.org> writes:
>Major versions in the url sounds good.

Just a "me too" post at this point, but FWIW I agree on major-version only in an API URL, for the reasons mentioned. (I realize there are larger API issues to be sorted out here, but hey, at least we've started with consensus on one small thing.)

Best,
-K

> CANHzzoNFzn9X5kG8bf2Wfk5u_EMNz%3D15cnt-yYzg3FNLkW6ZVg%40mail.gmail.com
> .

>
>
> For more options, visit https://groups.google.com/d/
> optout.
>
>
>

> --
> Semt feom a mobil dvice. Please fotgive any typps.
>
> --
> You received this message because you are subscribed to the
> Google Groups "hmis-api" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to hmis-api+u...@googlegroups.com.
> To post to this group, send email to hmis...@googlegroups.com.
> Visit this group at http://groups.google.com/group/hmis-api.
> To view this discussion on the web visit https://
> groups.google.com/d/msgid/hmis-api/
> CANHzzoOx4%3DUCfbmesedRKsrhxka2Mgq0X7-xDGX7epPNn0J_qA%40mail.gmail.com
> .
>