api resource naming convention

Not applicable

I have two backend services for customer inquiry, one for external clients and one for internal clients. I would like to expose them as two different REST APIs as below. Is this a good naming convention?

https://api.example.com/customerinquiry/v1/customers/external-customerinquiry

https://api.example.com/customerinquiry/v1/customers/internal-customerinquiry

Is this a good approach?

0 13 2,074
13 REPLIES 13

faijahmad
Participant V

there is no need to have two different API end points. You can pass type of client as uri param and just expose only

https://api.example.com/v1/customers/inquiry?type=external/internal

Not applicable

what if I want to expose it as two different APIs due to some business reasons?

faijahmad
Participant V

If business required two different API's , then go for it. Below may be nice. Let hope for more inputs on your question.

https://api.example.com/v1/customers/inquiry/internal

https://api.example.com/v1/customers/inquiry/external

I hope below below article will help to understand more.

https://medium.com/@mwaysolutions/10-best-practices-for-better-restful-api-cbe81b06f291

You can also google for more standard best practices about designing API.

What if I have two flavors for external inquiries like a salesman view and a manager view ?

Then it will good to pass these value via uri param as ?role=salesman/manager

is it a good idea to have the backend service as restful service? currently we are doing things in soap so api gateway can covert rest to soap. but what is the advantage if we do backend services also in rest ?

As APIGEE support both either Rest or SOAP as backend service. It really depend on business requirement like what kind of service to create as backend but as a next generation design , API are best !

I do agree it always better to design services for future. but what would I gain if I do backend service as REST API? My main concern is service contract. Today we use WSDLs that has XML as service contracts with clients. If I start using JSON, do I need to maintain different APIs for different clients since each client need a different data in response?

faijahmad
Participant V

So how you are maintaining as of now with WSDL ? Does each clients have different WSDL for providing them different data and in your backend have different logic to supply different data to each?

It would be better to pass client identification in param or header to supply them different data if there is some kind of privacy of data that other don't need to see.

**Personally , I always prefer API's as it is not tightly coupled

Not applicable

yes today we have 3 different response schemas within the same service and has logic based on client identifier. so if we go with APIs then do we can have same API for 3 clients and return JSON response. But what if a client receives additional fields later in the future? In a JSON response if we return additional fields that the client is unaware is that going to break the client code? or Is that quite normal in JSON since its kind name value pairs?

It won't be any issue until JSON is valid.

faijahmad
Participant V

This elearning class by APIGEE is really nice and informative about API Design . Please watch the series here.