This is a WIP as a style guide for an Independent Service. Clones of this file should reference this definition.
For the original style guide please see: https://github.com/OpenLMIS/open-lmis/blob/master/STYLE-GUIDE.md
OpenLMIS has adopted the Google Java Styleguide. These checks are mostly encoded in Checkstyle and should be enforced for all contributions.
Designing and documenting
Note: many of these guidelines come from [Best Practices for Designing a Pragmatic RESTful API] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)
- Result filtering, sorting and searching should be done by query parameters. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries)
- Return a resource representation after a create/update. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#useful-post-responses)
- Use camelCase (vs. snake_case) for names, since we are using Java and JSON. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#snake-vs-camel)
- Don't use response envelopes as default (if not using Spring Data REST). [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#envelope)
- Use JSON encoded bodies for create/update. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#json-requests)
- Use a clear and consistent error payload. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#errors)
- Use the HTTP status codes effectively. [Details] (http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#http-status)
- Resource names should be pluralized and consistent. e.g. prefer
requisitions
, neverrequisition
.
In most cases, the Hibernate DefaultNamingStrategy follows these conventions. Schemas and table names will however need to be specified.
- Each Independent Service should store it's tables in its own schema. The convention is to use the Service's name as the schema. e.g. The Requistion Service uses the
requisition
schema - Tables, Columns, constraints etc should be all lower case.
- Table names should be pluralized. This is to avoid most used words. e.g. orders instead of order
- Table names with multiple words should be snake_case.
- Column names with multiple words should be merged together. e.g.
getFirstName()
would map tofirstname
These naming conventions will be applicable for the messages property files.
- Keys for the messages property files should follow a hierarchy. However, since there is no official hierarchy support for property files, keys should follow a naming convention of most to least significant.
- Key hierarchy should be delimited with a period (.).
- The first portion of the key should be the name of the Independent Service.
- The second portion of the key should indicate the type of message; error for error messages, message for anything not an error.
- The third and following portions will further describe the key.
- Keys should use only lowercase characters (NO camelCase).
- If multiple words are necessary, they should be separated with a dash (-).
Examples:
requisition.error.product.code.invalid
- an alternative could berequisition.error .product-code.invalid
if code is not a sub-section of product.requisition.message.requisition.created
- requisition successfully created.reference-data.error.facility.not-found
- facility not found.
Note: UI-related keys (labels, buttons, etc.) are not addressed here, as they would be owned by the UI, and not the Independent Service.
See the Testing Guide.