API Gateway Patterns

[erewhon]

I've been thinking a lot about how services are organized and the API patterns that bind services together.  I'm interested in learning more about API gateway patterns, specifically like the "backends for frontends" pattern mentioned in Figure 4-10 here:

https://www.safaribooksonline.com/library/view/building-microservices/9781491950340/ch04.html

The above basically highlights that you maintain a backend gateway per user interface context: a "mobile" gateway, a "desktop" gateway, perhaps an "internal management" gateway.  Each of these gateways interact with decoupled services that exclusively own data according to however you've decided to partition your domain.  It seems that in this kind of architecture, you have some choices about your API design for these internal services: you expose APIs that are generalized enough to be used by *any* of the gateways or you create APIs that are specific to each of your gateways.  For example, your mobile gateway might only ever need to perform an update on a single user, but the internal management gateway may need to support bulk user update operations: do your internal services know about this distinction and model two separate API calls for each gateway?  My sense of it is that you are better off modeling your internal services as *agnostic* to the gateway context, but in doing so you typically have to work harder at building a more flexible API ... it seems to me that some interesting, general patterns for API development would arise out of this: e.g. that you should broadly support bulk updates, that you relax security controls around what can actually be updated, etc.  I wonder if this leads to a different architectural style for your internal APIs than those you expose to the clients.

Thoughts, feedback or references to other material on this subject would be amazing. :)

[Jack Repenning]

On Mar 23, 2015, at 1:52 PM, erewhon <keith....@gmail.com> wrote:

The above basically highlights that you maintain a backend gateway per user interface context: a "mobile" gateway, a "desktop" gateway, perhaps an "internal management" gateway.  

It appears to me that that diagram has something more elaborate in mind than perhaps you do. Certainly, the customer and admin apps may be completely disjoint. I've seen a few big sites that provide a fundamentally different service at their mobile portal. I can't say I'm fond of this approach in the first place, but if you really intend your mobile app to be utterly unrelated to your desktop app, then sure, why not serve them from separate portals?

-- 
Jack Repenning
Repenni...@gmail.com

[erewhon]

I think serving them from separate gateways has a number of benefits, not the least of which is a clear separation of concerns that is likely to marry up to your organizational teams (mobile team's needs are reflected by the mobile client gateway).  Anyway, what's more interesting to me is that these gateways implement patterns of composition from the underlying services and those services expose APIs with potentially significantly different requirements than your public API.  Depending on your design approach, it's possible these APIs need to become very "generalized" in how they serve data (again, depending on the approaches that I alluded to in the original post).  When designing APIs for internal services, it seems that things like generic batching and filtering mechanisms become more important for dealing with "bulk" transfers of data.

I'm just curious about people's experiences here and if there are good reference points in literature or in code somewhere that I could use to learn more. :)

[Kijana Woodard]

I think there's a general tendency [0] to conflate desktop client with "unlimited bandwidth and battery" and mobile as the opposite. [1] The user's form factor is beside the point. What's more relevant is the use case.

Take a [made up] api for Uber [2].  Is there any reason to have the "driver app" and the "rider app" use the same api? For most operations, you probably have to filter out one or the other. Why not separate them entirely? Same for central/corporate management.

From that pov, I prefer more specialized apis.

[0] I'm not asserting that either of you have done so.

[1] So is a laptop considered mobile today? What if I'm on my laptop in the park tethered to my phone? Stop sending me 10MB gifs!!!

2] The car service, not the hypermedia format. ;-]

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[erewhon]

LOL @ "stop sending me 10MB gifs!" ... definitely agree with you that use cases are important.  I think that in your example you may want to consider "driver" and "rider" internal services, but you'll still need a gateway to do things like composition.  Splitting that gateway along your platforms (desktop and mobile, for example) have more to do with the fact that your mobile teams are separate from your desktop teams and are driven by different features (use cases), but yet still consume core internal services (driver and rider services).

Even if you kept a single API gateway, I am still interested in examples of how people have chosen to design and separate the concerns between gateway(s) and internal services.

[Chris Mullins]

One of the issues with these types of gateways is that the folks who build these gateways (Amazon, Google, Microsoft, etc) don't generally talk about them. Not out of secrecy (although I'm sure there is an element of that), but simply because the need for such a gateway is fairly rare outside those environments. More specialized companies, such as Dropbox, have gone with different DNS endpoint simply to avoid needing to have a common gateway. 

Building a gateway is complex, and is full of pros and cons. Generally speaking, having different DNS names for basic partitioning will be easier. 

As a general pattern, I see:

https://api.company.com/{serviceProvider}/{version}/{service specific segments}?{service specific parameters}

The gateway routes to internal endpoints based on the combination of {serviceProvider}/{version}. 

For companies such as Google / Amazon / Microsoft there are huge benefits to this approach - you can have a single, highly specialized, team that deals with the boundary. This means that team worries about things efficient TLS termination, translation from a text protocol to a binary protocol such as Protocol Buffers, Bond, Thrift, Avro, or Coral, and all of the other craziness that comes from living at the Edge. This approach also makes dealing with DDOS easier, as the team that manages that endpoint lives in that space every day and is staffed for dealing with such issues. 

The downside is (obviously) the Single Point of Failure problem. Rolling upgrades across the front-end fleet, at least in my experience, is the biggest risk as there is No Place Like Production. No matter how you test, Prod (especially at scale) will expose bugs unique to that environment. 

Now, if we were to talk pure front-end API proxies, such as Azure API Management, Apigee (I think - I'm not very familiar with them), or others, then it's a slightly different and more nuanced topic. 

Cheers,

Chris

[erewhon]

Without a gateway, how does one achieve composition between services?  Do your services all talk directly to each other?  (e.g. if I ask for /customers/1234 and we want to embed their existing orders, does the customer service now have to talk directly to the orders service?)

K

[MattM]

I've lived in the "API Gateway" space for several years, and echo what Sam says in the book...  The concept of the API Gateway makes sense, but there are potential pitfalls that parallel the pitfalls of monolithic applications.  The concept of Microservices is so loosely defined, there is more art than science to how systems should be defined.  It comes down to what constraints you want to design for.  I think any of the following arguments could be made...

Option 1 - Deploy a monolithic API Gateway that supports multiple tenants and live with the impacts

Option 2 - Deploy a single API Gateway instance per frontend application (this is the BFF model) and live with some potential unnecessary redundancy; also, do these instances align with individual teams that will own and administer them?

Option 3 - Accept that Conway's Law is immutable and deploy an API Gateway instance per team that owns Microservices

Option 4 - Drop the notion of API Gateway completely and implement "Mesoservices" that are built on top of Microservices

Although Option 3 seems like the dirtiest of the first three approaches, it might be the most realistic.  Option 4 could be a repackaging of any of the others, since it could use an API Gateway under the covers to implement the Mesoservices.

I'm just spitballing here, but would love to have more detailed discussion on this topic.

[Kijana Woodard]

"Accept that Conway's Law is immutable..."

<3 <3 <3 <3 <3 <3 <3 <3 <3 

[Kin Lane]

Just for the record I'm buying MesoServicesEvangelist.com, MicroServicesEvangelist.com, and NanoServicesEvangelist.com.

Kin Lane (API Evangelist)

kin...@gmail.com

@kinlane

--

apievangelist.com

apisjson.org

apicommons.org

apistrategyconference.com

--

[erewhon]

Thanks for the reply!  Regarding Conway's Law, if you "accept" the law, I think you're only accepting that your organizational structures will be reflected in your system design, which I don't think necessarily precludes any of the options below.  Or at least, I don't think accepting the law necessarily makes option (3) the only viable one. :)

Option (3) suggests that each team owns a gateway and a collection of services (micro, macro, whatever), but doesn't really speak to how that partitioning should occur, which is really the difficult part of this discussion.  It's not like you can look at an organization and say "well, our teams are cut in this way, so let's build services that align with those teams".  I wish it was that simple (I realize this isn't what you're suggesting).  I think one of your organization's "communciation structure" includes the way you choose to internally address your users, which may include a "mobile development team" (or many of them).  How your business talks about and addresses classes of problems, markets and products will ultimately shape the most powerful/influential aspects of your communication patterns.

And I definitely agree that these design approaches are both an art form and could use more discussion...!

I know this discussion is veering away from more concrete aspects of API design, but nevertheless has a very significant impact on how you build those APIs, like I was trying to describe in my first post.

[Chris Mullins]

I think the word you're looking for here is Governance. A strong governance model is needed, although with an enforcement mechanism that relies on something other than Good Intentions (Good Intentions don't work. Mechanism's are needed. -- Paraphrased from Jeff Bezos).

When this goes well, you end up with a uniform set of APIs that span a company. When this goes horribly wrong, each team works in a vacuum and does everything totally differently. There are some big companies that you can see this in action at, and the impact it has on the adoption of services provided by those companies is non-trivial. 

For example, as a dev, I hate it when two different API's from Company X each do Pagination of Large Collections differently, or filtering, or sorting, or any of a dozen other simple, common, mechanical operations. Not because one mechanism is better or worse, but because dealing with this level of Conway's Law is stupid. Multiply this by 10 groups each putting out API's, or 100 such groups, and things get out of hand quickly. 

At the Enterprise Level the only comprehensive set of API guidance I know is OData v4. The pros/cons of OData (for me) is an entirely different discussion. 

Cheers,

Chris

[MattM]

I'll have to settle for macro.micro.meso.nano.services using the new domain model...  ;-)

[MattM]

I think the melodramatic point I was trying to make has been taken...  When it comes to Microservices, we have to factor in all of these different tech and non-tech dimensions.  With Conway, we know that the system mimics the organization, but trying to shape the organization in order to shape the systems is usually out of the developer's or architect's control.  So it's a constraint to be considered.  And there is no perfect system design, just an optimal one that depends on what you are optimizing for.

[MattM]

And the traditional approach to enterprise governance--epitomized by the whole SOA Governance movement--is diametrically opposed to the decentralized principles of Microservices.  So the question is how to come up with an approach to governance that empowers the decentralized teams, but incents them to do "the right thing".  Good intentions aren't enough, as Bezos pointed out, but a common cause that benefits everyone is usually more effective then a punitive one controlled by a small central team.  The open API movement on the web has proven this out when it comes to "use", since the APIs that are most accessible and usable generally get used the most.  Is there an benefit for Company X Team 1 do design their API in the same way as Team 2?  That's the main question to be answered if we want to avoid inconsistency.

(OK, I fully expect to be rightfully blocked from this thread now for starting multiple tangents :-) )

[Kijana Woodard]

Evolvable standards are hard. So enterprise architects wold rather just dictate the first thing that seems to work for the known use cases and that strains and creaks along until either individual teams subvert it in order to survive or the whole system crumbles and a new architect gets to design the "rewrite".

Hopefully a company has sufficient margins to absorb that cycle. If not....