Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

APIs as infrastructure: future-proofing Stripe with versioning

stripe.com

Post reply on HN
Print view View original

31–40 of 53 posts

Re: APIs as infrastructure: future-proofing Stripe with versioning

#31

Post by sleet »

kirbypineapple wrote: post #29

From a Stripe developer perspective this sounds like a really clean way to handle API versioning. From a consumer of Stripe's API's perspective, doesn't this make debugging or modifying legacy code a real pain? Let's say I'm using Stripe.js API's from a few years ago; where do I go to find the docs for that version? Do I need to look at the API change log and work backwards?

From the article:

"We also tailor our API reference documentation to specific users. It notices who is logged in and annotates fields based on their account API version."

Re: APIs as infrastructure: future-proofing Stripe with versioning

#32

Post by kirbypineapple »

sleet wrote: post #31
kirbypineapple wrote: post #29

From a Stripe developer perspective this sounds like a really clean way to handle API versioning. From a consumer of Stripe's API's perspective, doesn't this make debugging or modifying legacy code a real pain? Let's say I'm using Stripe.js API's from a few years ago; where do I go to find the docs for that version? Do I need to look at the API change log and work backwards?

From the article: "We also tailor our API reference documentation to specific users. It notices who is logged in and annotates fields based on their account API version."

Thanks for the clarification. I've used Stripe for side projects for over a year now and honestly didn't know about this until now (I haven't made almost any changes since I originally added Stripe integration). When viewing the Stripe API docs there is no sign in option, and only until I signed into my account did the docs provide a banner at the top indicating that I am on an older version.

I opened the docs in another browser to compare the differences and I am indeed seeing my older version when signed in. It's all very behind the scenes...I would have gotten tripped up by this had I tried to make changes to my code, and I wouldn't be surprised if many others have run into this issue.

My preferences would be for there to be multiple versions of the docs and have your version be very clearly laid out to you rather than automagically updating docs based on your pinned version.

Re: APIs as infrastructure: future-proofing Stripe with versioning

#33

Post by hn_throwaway_99 »

dperfect wrote: post #26
hn_throwaway_99 wrote: post #16

I think this is one area where GraphQL really excels. It essentially can handle all of this versioning for you (as clients specify EXACTLY what they want) - you just need to make sure that as you evolve your schema that existing fields are left as-is and you only add new fields (not an easy task, but no harder than what you have to do in Stripe's protocol).

New fields don't constitute the kind of backwards-incompatible changes mentioned in the blog post (adding fields is just as easy with RESTful APIs). GraphQL does help cut down on payload size (no extra fields for clients that don't need them), but if you're making major changes to the shape of your data, you'll still need to write some kind of compatibility layer.

I've done this with GraphQL (major changes to the shape of the data), and I still think it's easier than other approaches.

For example, in those cases where the response object was fundamentally different, I've added a whole new Query field (and Mutation field) at the top level, that returned the new object. Under the covers there was still a bunch of complexity needed to support both top-level query fields, but old clients continued to access the old query, and new clients went to the new query.

Also, two other things I really like: With GraphQL it's trivial to log which clients are accessing which fields (at some point you can just decide to kill old ones). Also, the @deprecated support in the GraphQL schema IDL integrates wonderfully with the GraphiQL tool, so anyone browsing your schema for the first time always sees the recommended latest version that they should use.

Re: APIs as infrastructure: future-proofing Stripe with versioning

#34

Post by jbrooksuk »

tomschlick wrote: post #3

To me this is one of the best things about the Stripe API. It's basically database migration files but for your API requests. Does anyone know of packages that do this already? I have been contemplating creating one in PHP/Laravel for a long time but haven't had the time yet...

I’ve been looking for something like this in PHP too. Nothing yet though. Happy to work on something with you though!

Re: APIs as infrastructure: future-proofing Stripe with versioning

#35

Post by michaelchisari »

organsnyder wrote: post #4

I work on a SOA team at a large healthcare enterprise. We currently write mostly SOAP APIs (yeah, I know, 2017 and all that...), and follow a typical pattern as what Stripe describes: Whenever we do a version bump (which is extremely frequent, since a WSDL breaks a contract the moment you sneeze at it), we create an XSLT transform from the new version back to the old. So if you're calling version 2, but the current v…

> Essentially, the old version becomes a consumer of the new version

As a raw concept, I really like this idea. Let's say you're bumping from 2.5 to 2.6 and there's a breaking change in-between.

You replace the old api code with a new thin layer that consumes 2.6 and puts it in 2.5 format. This would be easy to write a series of tests for to make sure that 2.5 is still providing what it should, and it has the added benefit of giving your engineers the opportunity to consume the new api internally in a structured way, so that would be a good way to catch any bugs you might not otherwise find.

And of course, the 2.4 version already only consumes the 2.5 version, so it's turtles all the way down.

That's a great concept. You would have to still deprecate APIs or provide an incentive for users to update to the newest version, otherwise the oldest versions would create a long chain of requests that add unnecessary overhead. But otherwise I love it.

Re: APIs as infrastructure: future-proofing Stripe with versioning

#36

Post by tenken »

jbrooksuk wrote: post #34
tomschlick wrote: post #3

To me this is one of the best things about the Stripe API. It's basically database migration files but for your API requests. Does anyone know of packages that do this already? I have been contemplating creating one in PHP/Laravel for a long time but haven't had the time yet...

I’ve been looking for something like this in PHP too. Nothing yet though. Happy to work on something with you though!

Hmm https://github.com/thephpleague/fractal

And it's underlying Transformers object API .... ?

Re: APIs as infrastructure: future-proofing Stripe with versioning

#37

Post by pbreit »

organsnyder wrote: post #4

I work on a SOA team at a large healthcare enterprise. We currently write mostly SOAP APIs (yeah, I know, 2017 and all that...), and follow a typical pattern as what Stripe describes: Whenever we do a version bump (which is extremely frequent, since a WSDL breaks a contract the moment you sneeze at it), we create an XSLT transform from the new version back to the old. So if you're calling version 2, but the current v…

If you can do an XSLT transformation to different versions I wonder how important the change was in the first place?

Re: APIs as infrastructure: future-proofing Stripe with versioning

#38

Post by tomschlick »

jbrooksuk wrote: post #34
tomschlick wrote: post #3

To me this is one of the best things about the Stripe API. It's basically database migration files but for your API requests. Does anyone know of packages that do this already? I have been contemplating creating one in PHP/Laravel for a long time but haven't had the time yet...

I’ve been looking for something like this in PHP too. Nothing yet though. Happy to work on something with you though!

I'm gonna hack on it a bit tonight before I go to bed. Here is the link: https://github.com/tomschlick/request-migrations

Re: APIs as infrastructure: future-proofing Stripe with versioning

#39

Post by organsnyder »

pbreit wrote: post #37
organsnyder wrote: post #4

I work on a SOA team at a large healthcare enterprise. We currently write mostly SOAP APIs (yeah, I know, 2017 and all that...), and follow a typical pattern as what Stripe describes: Whenever we do a version bump (which is extremely frequent, since a WSDL breaks a contract the moment you sneeze at it), we create an XSLT transform from the new version back to the old. So if you're calling version 2, but the current v…

If you can do an XSLT transformation to different versions I wonder how important the change was in the first place?

Our most common case for this is adding a field to a data model: that will break a SOAP client. The XSLT just strips out the new field.

Re: APIs as infrastructure: future-proofing Stripe with versioning

#40

Post by lifeisstillgood »

michaelchisari wrote: post #35
organsnyder wrote: post #4

I work on a SOA team at a large healthcare enterprise. We currently write mostly SOAP APIs (yeah, I know, 2017 and all that...), and follow a typical pattern as what Stripe describes: Whenever we do a version bump (which is extremely frequent, since a WSDL breaks a contract the moment you sneeze at it), we create an XSLT transform from the new version back to the old. So if you're calling version 2, but the current v…

> Essentially, the old version becomes a consumer of the new version As a raw concept, I really like this idea. Let's say you're bumping from 2.5 to 2.6 and there's a breaking change in-between. You replace the old api code with a new thin layer that consumes 2.6 and puts it in 2.5 format. This would be easy to write a series of tests for to make sure that 2.5 is still providing what it should, and it has the added b…

Don't you mean the other way round? You always want to be running the most recent 2.6 servers, but when someone sends version 2.5 requests you transform the 2.5 to 2.6 and pass it along to your server (and vice Verda with responses)

The problem I guess is breaking changes come easily - it's fine if say we have example.com/homeaddress and now I add a zip code field in 2.6 - but a 2.5 request has no zip code and if 2.6 makes that mandatory it's really 3.0 - that just feels wrong. But it's a breaking change so, ok. But you get a deeper discussion then over why make a lack of zip code a breaking chnage ? Interesting

Post reply on HN