RESTful API design : Microservices — Continued .. Guideline /Documentation

General Guidelines for API

As such there is no industry standard, but below is the case preferred to use.

In case of property name

· Use camelCase and keep consistent across all API’s

· Array name should be plural

· Reserved keywords should be avoided

For property value

· Empty array should be represented by []

· Boolean properties must be null

· Null value should have their field

Naming

· URL contains long path url : Path segment must be lowercase and separated by hypens

e.g. /customer-details/{customer-id}

· Query parameter must be in lower case and separated by hypers in case of long

e.g. api/customer-details?customer-number=007&order-id=007

· Prefer Hyphenated-Pasacal-Case for HTTP header fields

· First path segment should be /api

· Avoid trailing slashes

· Use conventional Query string for limit(no of entries,offset (numeric pffset page start) ,and sort

· Always use pluralized resource name

Documenting API

In Restful API, It is very important to document the implementation .It make easy to understand and use . There are many tools available .Below is the list having few of them

· Swagger : https://swagger.io/ — Open source tool https://swagger.io/specification/

· Spring Rest Docs : http://docs.spring.io/spring-restdocs/docs/1.0.0.M1/reference/html5

· RAML: http://raml.org

· ApiDocJS : http://apidocjs.com

· SpringRestDoc : https://bitbucket.org/tritales/springrestdoc/overview

Happy learning …
If this post was helpful, please click the clap 👏button below a few times to show your support