API Best Practices and Standards

[bkr vandana]

Hello All,

I have recently started my journey with API designing. 

We are designing RESTful APIs. Have few questions related to API header, best practices, Query parameters, GET Vs POST?

What are the best practices to keep a clean and simple header ?

If I'm going to use CORS, do I need to always consider the parameter related in header ?

Is custom header is a good idea to use ?

Versioning - is a good to keep in URL or header ?

While using GET, if the parameters are contains sensitive/secured information it is not safe to pass through URL, especially in this case is it good to use POST  instead of GET, and all the parameters can be passed through body instead of header.? Do we have any disadvantages here ?

We have few REST services (exposed to presentation layer) are integrated with SOAP services  and the responses are converting from SOAP to REST (while displaying to UI layer) and all the custom header parameters are in SOAP, is it safe to keep in part of URL. Or is it better to keep a custom header in REST and do the SOAP REST transformation ?

I'm looking for your guidance/response.

Thanks in advance !!

Regards,

BKR

[Lukas Rosenstock]

Hello BKR,

it’s difficult to answer your questions without knowing more about your use case, so let me try to give some general advice.

What are the best practices to keep a clean and simple header ?

If I'm going to use CORS, do I need to always consider the parameter related in header ?

Is custom header is a good idea to use ?

Regarding header, I think it’s best to avoid custom headers unless you really need them, meaning there’s no standardized header for your use case and you feel that semantically the information doesn’t belong in the query or POST body. Also CORS requires whitelisting or preflight so without custom headers, CORS is easier.

What is it that you want to accomplish with custom headers?

Versioning - is a good to keep in URL or header ?

For versioning, I think putting it in the URL is easy to implement and understand but there are some arguments against it, too, though I don’t see technological disadvantages.

While using GET, if the parameters are contains sensitive/secured information it is not safe to pass through URL, especially in this case is it good to use POST  instead of GET, and all the parameters can be passed through body instead of header.? Do we have any disadvantages here ?

The disadvantage of using POST where GET would be the appropriate choice is that it goes against the semantics of HTTP and could cause confusion with developers, also if you have a caching layer it won’t work.

We have few REST services (exposed to presentation layer) are integrated with SOAP services  and the responses are converting from SOAP to REST (while displaying to UI layer) and all the custom header parameters are in SOAP, is it safe to keep in part of URL. Or is it better to keep a custom header in REST and do the SOAP REST transformation ?

It seems you have a custom layer to transform REST to SOAP because there’s SOAP in the backend but the client uses the REST API, right? In that case the client doesn’t and shouldn’t care that there is SOAP in the backend so you should think about the API exposed to the client only in REST terms and not pass through any SOAP data.

Hope I could help!

Lukas Rosenstock

https://cloudobjects.io/

[miqui]

@BKR,

>>

It seems you have a custom layer to transform REST to SOAP because there’s SOAP in the backend but the client uses the REST API, right? In that case the client doesn’t and shouldn’t care that there is SOAP in the backend so you should think about the API exposed to the client only in REST terms and not pass through any SOAP data.

>>

..totally agree with Lukas,  but the real challenge is for the developer of the REST API who in many cases has to do some mapping tricks, etc.. when consuming multiple SOAP services to generate the desired representation ...sometimes i see "SOAPiness" leak to the actual REST interface

rgds,

Miguel