How to encode an API endpoint that has a version


#1

The API I’m working with allows users to retrieve a register of controlled terms, say:

GET /product-codes

It also allows users to retrieve previous versions of the register, by appending a version identifier:

GET /product-codes:10

to get version 10 of the register rather than the most recent. I’ve tried encoding this endpoint in my RAML file, but with little success so far. I’ve tried:

/:{register}::{version}:
/:{register}\::{version}:

but both of them confuse the parser I’m using (raml-1-parser-browser from NPM). What would be the correct way to encode my endpoint in RAML?


#2

/product-codes can return the latest version
/product-codes/10 can return version 10.

However, that is not backwards compatible with old clients that are expecting /product-codes to return version 10 structure.

You could use a query parameter, but I am not sure you can return different objects for the same resource, depending on a query parameter value.

I use http://hostname/apiname/v{version} in the URL and return accordingly. However I am not sure it is the best way.


#3

HI @rojocapo,
Thanks for your answer but I don’t think I explained myself clearly enough. The API already exists and isn’t going to change, I just need to find a way to document it with RAML. Re-designing the versioned-URLs isn’t in scope for this exercise.

Regards,
Ian


#4

Have you tried something horrible like this?

/product-codes:10:

see http://www.fileformat.info/info/unicode/char/003A/browsertest.htm

I am not sure about how to UTF escape the resource names, sorry


#5

Ouch. Painful seeing an API designed this way. I would urge you to ask your team/architect/whoever if very soon can you fix this (using RAML and RAML-to-… generators if possible) to provide a better API to your API consumers.

First thing is… if you are going to have versions of your data, at least use a query parameter to specify the version. Hopefully you are able to use JAXRS or something on the server side where it can really help you with this sort of thing.

I wish I could offer more info on documenting with RAML. I have been fortunate enough to be able to design the API with RAML first, then generate/implement code… the right way. :smile: I have seen a lot of already existing APIs that want to use RAML to document, and while not a bad thing… it truly does not take that much time to turn RAML into code that you can then be in a position to use your RAML as the single source of truth for your API and build everything from it. Unfortunately I have come across developers that are stuck in their ways and either dont grasp the amount of time this saves and ease of doing so, or are just too stubborn to acknowledge there is a better way to design and implement APIs.