Proxy or Product -Logical split up design

[#1]

I have a design level query on API proxies and products.

The below is my understanding.Please correct me if anything wrong and also provide me best design solution.

Is it good idea to logically split up proxies and add those proxies in individual products for the consumers' access?

-This can reduce more number of resources getting added to the same proxy.Although they are all intended for same business functionality ,logically grouping them into different proxies can avoid proxy becoming huge and also leads to easy maintainability.When there is more updates to the resources under one proxy as the resources are unstable,not many will get impacted due to the changes.

Is it good idea to logically split up products by choosing only the needed resources of a proxy into one product ?

-This will avoid splitting up multiple proxies when we can implement the feature of choosing resources of a proxy in a product.Not much sure about the advantages of this feature.

[#2]

Please provide some update on this.

[willwitman]

Hi @RK4

These are great questions. I hope others will add comments here, because we don't have any specific guidance documentation on this.

I don't think you'll find any right/wrong answers. A lot might depend on what you're trying to do, the scope of your project, how many developers are working on it, etc.

I helped with a demo project called StreetCarts and we ran into some of the same issues. Especially with your question #1, we split up proxies functionally to avoid having one or two monolithic proxies. It was nice that way with multiple people working on the project at once. Each team member could work on a proxy without much interference.

It might be useful to think of products as more of a business-case feature, rather than a development feature. So, I'd say design your proxies as it makes sense for API developers, and products as it makes sense for publishing your APIs.

It'd be great to see others add to this thread.

[#4]

Thanks for your response @wwitman.Nice reply 🙂

As you said,let me also wait for others to respond.

[sarthak]

@RK4 Here's my 2 cents on this topic:

Proxies and Products are two completely different entities serving different purposes. When you design a Proxy you should not think about Products and vice versa.

Proxies are designed by engineering/IT team. Proxy design will be based on internal reasons like - team alignments, number or APIs, versioning strategy of APIs, common business logic served,SDLC needs etc. It is a pure technical decision.

Products on the other hand are typically not a technical decision if used in the intended way. If you are running a large enough API program - might be internal,partner or open API program then API products are the mechanism through which you expose those APIs. Lot of times business people decide how the products should be designed. It's design can be driven by changes in external systems like Salesforce where your business folks already design different product line items/SKUs.

API Consumers will never see a proxy where as IMO an API developer should not be bothered about how API Products are constructed. Only thing an API developer should be bothered with are the different capabilities offered in the API products - like rate limiting,oauth Scopes etc. because based on those capabilities they have to write the policies. But he/she should not be bothered about the different products and how are they grouped.

[#6]

Good one @sarthak

So,designing API proxy and Product are mutually exclusive tasks.

First we do API Proxy design and need to consider only proxy developers and maintainance.

Next API product design considering only the Consumers needs.

Almost all the answers are hitting the same point..

[ceber]

I think the other answers are here are good. I wanted to pick out part of what Will said to emphasize, and rephrase a little.

1) Design to simplify for the consumer. Don't make it hard for developers to find the right APIs, get access to the right APIs, or maintain their apps.

2) Don't make it hard for you to maintain. You've already hit on this idea which is great.. keep things simple. Think about needing to change parts of the whole, etc. Except where doing so would conflict with the first rule.

3) Be consistent across audiences, products, development teams, etc. Except where doing so would conflict with the first or second rules.

[#8]

This is a very interesting question. There are many valid answers, but the right one depends on your use cases: api consumers / devs and api programmers. My main suggestion is find out the simplest api proxy / product approach that will work for your needs. Over time as the needs change, you will run into a need to refactor or re-work the api proxies and products. You will want to make that task as simple as possible.

If you have a variety of teams with different roles / permissions that are going to be working on the API, your best approach would be to break up the proxies into smaller units. You can then use revision control and only give devs access to the proxies that they can modify. On the other hand if the permissions are the same for the devs and the API proxies share a lot of logic, big monolithic proxies could save you quite a bit of time.

As far as product goes, they are more of a business decision. This is how you expose APIs to api consumers. Things such as rate limits, quotas and permissions of your APIs are exposed at the product level. You could for example have two different products for the same proxies, but they could have different quotas based on developer permissions / roles / paid level. If things such as quota and rates are not how you differentiate your API offerings, user or application groups might be another valid approach. For example, you can create API products to group together the APIs needed to work on user needs that are related.

[ksprashu]

@RK4 here are my 2 cents.

Many have said exactly the right points, however I will give you an example of how I would go about a complex proxy + product.

Firstly, a few key messages

+ Build for maintainability

+ Build based on the consumption patterns

+ Build based on the exposure granularity needs

+ Keep it consistent

Let me explain.

I always prefer maintainable code, so I would like to not bloat one single proxy with 20+ resources. That said, split the proxy based on the consumption and exposure needs and not just any random separation of code.

For example, if I have a store in which I have a set of items and these items can be searched, added to shopping cart, and finally checked out. Additionally I have the item management APIs which allow me to add / remove items, change quantities etc.

My consumption needs might be as follows

1) Guest users : Can search for items

2) Logged in users : Can add items to shopping cart and checkout

3) Store managers : Can modify items + quantities

My exposure needs might be as follows

1) Free tier : Item Availability Search APIs (quota restricted)

2) Paid tier : Apps to add item to shopping carts and checkout

3) Internal : Backend to manage inventory

Based on this I would organise my proxies as below (Note: these are high level resources and very indicative)

1) Proxy 1 :

GET /items/:id

GET /items?<filters>

2) Proxy 2 :

POST /shoppingcart

PUT /shoppingcart/:id

POST /shoppingcart/:id/checkout

3) Proxy 3 :

POST /items

PUT /items/:id

DELETE /items/:id

and so on...

What I am trying to say is that I might be tempted to put all item API in one proxy, all shopping cart APIs in another. But that is a technical separation and not a logical separation.

Final message - to each one his own, but the bottom line is to keep everything consistent and finally that is what will help maintainability.