Resource Naming following REST Practices

[ateebshaik]

Hi ,

I would like to get a clarification for designing the proxy endpoints. If a backend service is not follow REST naming standards for resources  example \account\{id}   instead of \accounts\{id} . Is it not gateways responsibility to transform the path to REST and expose them. 

The challenge I am facing here is with the Telecom domain where the backend services follow  Open API Standard (TM Forum) but are not restful while naming the endpoints  like \account , \account\123 . without any plurals . Should I change them to REST when exposing them?

[dchiesa1]

If a backend service is not follow REST naming standards for resources example \account\{id} instead of \accounts\{id} . Is it not gateways responsibility to transform the path to REST and expose them.

I would not say that "it is the gateway's responsibility" to transform paths. Maybe phrased a little differently, "it is the gateway's opportunity" to do so. Some people want to use the gateway layer to do such transformations, and some do not. Simply appending an s ("pluralizing") collection names seems like a minor change to make, I'm not sure I would use the gateway for that purpose. On the other hand if you plan to expose a myriad of APIs from different sources, and they all use different path conventions, that can be problematic for developers trying to use the APIs. And so using the gateway to act as a facade, to provide consistency across all the disparate APIs, would be a good use of a gateway.

The challenge I am facing here is with the Telecom domain where the backend services follow Open API Standard (TM Forum) but are not restful while naming the endpoints like \account , \account\123 . without any plurals . Should I change them to REST when exposing them?

I think RESTful guidelines are guidelines, not hard rules. They exist to provide a common consistent model. It does feel "wrong" for a path segment that refers to a collection, to not use a plural noun. But it's not a great impediment to a developer's ability to understand the intent of the API. so as a violation of the guidelines, it's a relatively minor one. If you had other APIs that used plurals for collections, then I'd want them to be consistent, and I'd configure my gateway to make them so. But ... if it's just this one API, then I might leave it.

[ateebshaik]

Hi Dino,

Thanks for the response. I agree with you these are mere guidelines . But gateway is exposing other target endpoints like microservices or other ESB services which are following REST in terms of not just defining the resource pluralization but also aligning with the parameters sequence. For example  defining ( /extcustomercontracts/carts/{cart-id}/customer-contracts/{customer-contract-id}/scope ) is in align with the sequence of Uri parameters and REST standards.  Where as the TM Forum ( Open API) does not align with the pluralization  or  the sequence - for the above example the endpoint that they have defined is  (/extcustomercontract/carts/{scope}/{cart-id}/customer-contract/{customer-contract-id} )  where my understanding is carts should be followed by {cartid} .

I was looking to make it standardized as the other proxies (with target as microservices) follow the REST standard where as all the TM Forum API's that are being exposed through the same Apigee gateway (with Different Proxy name) are not aligned with REST.

The push back when I ask the backend team to let me make them standardized at the gateway so that I can align with the other proxies is that as these are Standard TM Forum (Open APIs ) the consumers are  aware of these API's and  they  expect to be consumed as they are and any URL  change would make it difficult for them to link them up .

I Would like to know your view on this if I need to leave them as they are or make them aligned with other API's 🙂 

Link for the Tm forum API's  : https://projects.tmforum.org/wiki/display/API/Open+API+Table

[dchiesa1]

Hmm, yes I see. 

ok the rest of this is all just my opinion. 

Standards are important.  Even if they violate some aesthetic norms, standards help by being the same everywhere.  So I'm sympathetic to the argument that the TM Forum APIs need to remain as is.

I am also sympathetic to the idea of RESTful design, pluralized container objects represented in path segments.

I think my first choice would be to just let the TM Forum APIs be as they are.  There was a standards group who defined the API, it's codified, and it's written down, and there's no going backward. Also they're extensive.  There are many independent APIs under TM Forum.  And we suppose they are all internally consistent.  So in the interest of supporting and benefiting from standards, just support them, keep them as-is. 

A second option MIGHT BE to provide a non-standard API wrapper on top of the TM Forum API.  That could be more limited, and also could potentially conform to REST conventions more closely.  I'd do this only if I thought there would be a significant benefit for consuming developers. 

OK that's my quick opinion. Other people will have different opinions, equally valid!