API versioning with routes using Pyramid

[Oleg Borisenko]

Hello. I want to get API-versioning functionality and I wonder how to do it in Pyramid correctly.

Conditions:

1) I want to have two simultaneously working APIs

2) I want to have the following notation:

   /v2/veryimportantroute

   /v3/veryimportantroute

   /veryimportantroute - this one should by default use some of specified API versions

3) I would like to make minimum changes to currently existing code

What's the most correct way to do this? I know that I can implement some kind of 'predispatcher' but it seems that it's not quite an easy way.

[Mike Orr]

I would first question whether '/veryimportantroute' is necessary
because that causes most of the complication. Can't the clients
explicitly call the version they're compatible with? Or can't your
view handle all request versions, either by noticing that a new
argument does or doesn't exist or has a different format, or by a
'version' argument? Or can '/veryimportantroute' simply redirect to
the latest version?

If all the views are different, you can handle this in the view
configuration, by tying route 1 to view A, route 2 to view B, and
route 3 to view B. (Or a redirect view, or do the redirect in
Apache/NGINX.)

If it's all going to a single view, then the view may need to know
whether 'v2' or 'v3' was specified. (This is equivalent to a 'version'
argument, but in the URL.) If you have a single route, then the
version can be a match variable. If you have two different routes,
then it won't be a match variable and you'll have to determine it via
some other trickery (such as a custom route predicate, or have the
view look back on the path, but both of those can be inelegant.

If you tell us some more about when/how you expect the API to change,
and whether there will be a separate view for each version or one view
for multiple versions, then we could answer it more precisely. Or if
the answer is, "I don't know and I just want to generally future-proof
the site", then the answer may be "We don't know what to do because we
don't know what kind of need will arise". If there's only one version
now, you could either put '/v1' in front of everything just in case,
or leave it out until the future reveals what you'll need. You may
find you won't need the version prefixes: the view can simply deduce
what version the client is from the arguments, and return a response
for that version. Or if a new API has actual new URLs (new views),
then they'll never be called in the old version or if they are it's an
error.

--
Mike Orr <slugg...@gmail.com>

[Jonathan Vanasco]

We typically handle it like this...

For these routes/files

      /v2/veryimportantroute  <> views/api/v2.py

      /v3/veryimportantroute  <> views/api/v3.py

we tend to proxy the actual API functions to something like

lib.api.veryimportantroute.py

    def v2()

    def v3()

the url routing is straightforward, and it reduces the work involved in API releases

[Oleg Borisenko]

No, it's not a "future" request :) The issue with default API version is related to desktop application that can't be easily updated by users. And this application tries to get our "v2" API.

At the same time we want to make totally new (additional) API version with support for GraphQL and to maintain backward compatibility. Of course we could leave our existing routes and start defining new routes with "/v3" prefix but it seems to be an ugly way to do.

The routes are quite different.

Of course "manual" routing is possible but I assumed that there is some semiautomatic way to do it.

[Mike Orr]

It's not that ugly. The v2 routes are legacy routes. If it's an API,
users won't be typing it directly or seeing it in the location bar, so
the only ones who will see it are application developers.

/v2 may not be worth it because you have to support the legacy URLs
anyway, and you're expecting new applications to use /v3.

> --
> You received this message because you are subscribed to the Google Groups
> "pylons-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pylons-discus...@googlegroups.com.
> To post to this group, send email to pylons-...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pylons-discuss/a5cf34bd-e683-4550-9d7e-6684b950a15e%40googlegroups.com.
>
> For more options, visit https://groups.google.com/d/optout.



--
Mike Orr <slugg...@gmail.com>

[Sadegh Nikaein]

whats your routing system? url dispatch or traversal ? 

if use url dispatch take look at route prefix 

[Oleg Borisenko]

Thanks, that's looks like just what we need!