Layer7 API Management

Expand all | Collapse all

General best API design approach validation required

Jump to Best Answer
  • 1.  General best API design approach validation required

    Posted 01-24-2017 01:14 PM
      |   view attached



    Can someone help me to validate our API designs? Because one of our colleague has raised concern on our design and would like to hear if we are going in a right path. 


    I would describe two approaches here, one which we are implementing and the other one suggested by my colleague. 


    As I am not sure what to call these patterns in API design terminology, I gave some names to them for our reference


    Composition Pattern:

    Currently we are following this pattern. 

    1 - One Policy

    2 - Supports multiple Http Methods

    3 - Base URI*



    Policy: Create, Update and Get Employee Profile

    Base URI   : /company/v1/employees/profile*

    HTTP Methods Support: POST/PUT/GET


    All below scenarios are supported in single policy and routed to backend service

    1. /company/v1/employees/profile   POST

    2. /company/v1/employees/profile   PUT

    3. /company/v1/employees/profile/{SOURCEID}/{ID} GET

    4. /company/v1/employees/profile/{SOURCEID}/{EMAIL} GET


    Backed system supports the same URIs. No much logic involved in routing.



    Parent - Child Policy Pattern (Suggested By my colleague)

    Parent Policy with similar configuration specified in Composition Layer. 

    - Instead of routing to backend service from directly from Parent API route it via child policy. 

    - It means, create a individual policy for each scenarios as listed below

    1. /company/v1/employees/profile/create   POST

    2. /company/v1/employees/profile/update   PUT

    3. /company/v1/employees/profile/get/{SOURCEID}/{ID} GET

    4. /company/v1/employees/profile/get/{SOURCEID}/{EMAIL} GET


    Configure backend service routing URI in each policy. 

    Publish all sub policies to Portal as Private policies. 


    Advantages are:

    1. Metrics collection at each HTTP method level. 

    2. If POST Policy is down due to some reason other policies are still available. 


    Which is the best practice to implement in Gateways?

    What are the advantages and disadvantages of each approach. 


    I am not sure up to what extent I have conveyed my understanding but tried to place as much as possible. Attached is the image with simple diagram for both the patterns. 




  • 2.  Re: General best API design approach validation required

    Posted 01-24-2017 05:45 PM

    Hey Kareem,

    I think what you will more commonly find is an approach that is closer to your 'Composition Pattern'. You basically have a resource in your URI, and you utilize http methods to do CRUD against said resource, then use parameters to filter the data returned.


    You still can produce KPI's at the http method level, using an Access Log type of concept with either method, so this shouldn't effect your decision in my opinion.


    Hope this helps,



  • 3.  Re: General best API design approach validation required

    Posted 01-31-2017 03:56 AM

    Thanks for the information Doyle. 


    One more thing is, 


    is it best practice to have separate policy for each CRUD operations(POST, PUT, GET)?


    I agree on GET, we can have a separate policy, but POST and PUT can be on the same Policy right?


    We have received a recommendation for this kind implementation as it has some advantages as listed below:

    1. High loads can be shared across APIs. 

    2. If any of one API is affected or down, others can still accessible. 

    3. Metrics can be collected for each CRUD operation. 


    But it increases the no. of policies and unnecessary and hence increase in maintenance right. 


    Can you suggest the industry best approach for this?





  • 4.  Re: General best API design approach validation required
    Best Answer

    Posted 01-31-2017 05:22 PM

    Hello Kareem,

    My understanding is that,

    1. I don't think the loads can be shared across APIs, the loads only share across the gateway servers in the cluster. The gateway is multi-threads, single API or split to multi-APIs have no difference on handling concurrent requests.

    2. the same, there is no single API down, a service is not available usually means the gateway down, all the services on this gateway won't be available.




  • 5.  Re: General best API design approach validation required

    Posted 02-02-2017 04:58 AM

    Thanks Mark, this helps us to have some clear understanding. 




  • 6.  Re: General best API design approach validation required

    Posted 01-31-2017 07:03 AM

    Hi Kareem,


    I would be inclined to go with the first approach.  You call it a "composition pattern", but I view it as just being "resource oriented" which falls more in line with a RESTful style to service orientation.  Having discrete policy for each HTTP verb is overkill in my opinion.  Metrics can be gathered by HTTP logs or audit capture.  


    If you are concerned with the uptime of your backend service, you could cluster multiple service instances behind a load balancer and expose a virtual host.  The API Gateway also allows you to declare multiple hosts that you could route to.  This would be another form of load balancing done at the gateway tier.  This would give the ability to add/remove instances of your service to accommodate higher loads, for example.


    I actually don't think it is best practice to have separate policy for each operation (at least to start with).  It complicates your deployment for little benefit.  I'd go with a resource oriented approach first.  It is the simplest to understand and deploy.  When you have this in place, learn how your service is actually being used before complicating the policy around it.


    Do you have other requirements that would justify one policy per operation?  I could think of a couple of use cases, but they are edge cases in my mind.


    Hope that helps.



  • 7.  Re: General best API design approach validation required

    Posted 02-02-2017 05:00 AM

    Thanks Alejandra, 


    We know this is not a right approach and your points give us more clarity and reasons why we shouldn't do this.