MOSIP REST API guidelines
1 Introduction
1.1 Context
MOSIP is developed as an open source framework project. The code developed complies with the Java standards and best practices.
1.2 Purpose of this document
This document gives various RESTful webservice standards which have to be followed during the MOSIP development.
1.3 Scope of this document
This document covers the coding standards, which are followed by the RESTful webservice developers.
2 URL structure
2.1 General structure
The syntax of the URL of the RESTful webservice should be as follows for all the modules except Kernel,
https://<IP_ADDRESS>:<PORT>/<MODULE_NAME>/<VERSION>/<RESOURCE_NAME>/<PARAMETERS_AND_VALUES_IF_ANY>
For example,
https://mosip.io/pre-registration/v1/document
Only in case of Kernel modules, the <MODULE_NAME> is not included. The format is as follows,
https://<IP_ADDRESS>:<PORT>/<VERSION>/<RESOURCE_NAME>/<PARAMETERS_AND_VALUES_IF_ANY>
Following URL is an example for Kernel,
https://mosip.io/v1/emailnotifier
The convention is, before <RESOURCE_NAME>, we should have the version number.
The URL is the sentence, the resources are nouns and the HTTP methods are verbs. The URL, before the parameters, should contain only spinal case ( - ). The URL, before the parameters, should not contain snake case ( _ ) or camel case. NOTE: The parameters can contain snake case or camel case.
3 Resources - Usage of nouns and verbs
Use nouns for CRUD operations. Resource GET read POST create PUT update DELETE delete /preenrolments Returns list of pre enrolments Creates a new pre enrolment Bulk updates Delete all preenrolments /preenrolments/123 Returns a particular pre enrolment Updates a specific car Deletes a specific car
For operations, wherever applicable the operations can be added as part of the URL itself. For example, /getAllPreenrolments /createNewEnrolment /deleteAllPreenrolments
4 Resources – Usage of plurals in nouns
Use the plural nouns in the resource names if there is CRUD operations. For example,
https://mosip.io/pre-registration/v1/individuals Prefer
https://mosip.io/pre-registration/v1/individual Avoid
In other cases, use singulars in the nouns. For example,
https://mosip.io/pre-registration/v1/OTP
5 Resources – actions in the URL
The actions are added in the URL, wherever applicable. For example,
https://mosip.io/pre-registration/v1/OTP/generator
https://mosip.io/pre-registration/v1/OTP/validator
6 Appropriate usage of the HTTP methods
Use only the intended purpose of the HTTP methods. For example, do not use POST to update a resource or PUT to create a resource.
7 HTTP Status codes
In all the success cases and failure cases, 200 HTTP Status code is returned. Based on the "errors" JSON element in the response, the caller can decide whether the call is success or failure.
8 Identifying a resource
When the caller want to identify the resource, the path param is used. For example,
https://mosip.io/pre-registration/v1/individuals/id1234
9 Filtering
The filter has to be applied via the URL parameters. For example,
https://mosip.io/pre-registration/v1/individuals/id1234?city=someCityName&pincode=473822
10 Sorting
In case if the results have to be sorted, it can be mentioned in the URL parameter named sort. For example,
https://mosip.io/pre-registration/v1/individuals/1234?sort=firstName
11 Pagination
In case of pagination, the page number can be mentioned in the parameter by the name “page”. For example,
https://mosip.io/pre-registration/v1/individuals/1234?page=15
12 Always use SSL
Always use SSL for the services. No services should be exposed without SSL.
13 Versioning
Always version the service. The version have to be mentioned in the URL of the service after the hostname (and port number, if any). For example,
https://mosip.io/pre-registration/v1/individuals/1234 --> Except Kernel module
https://mosip.io/v1/individuals/1234 --> Kernel module
14 Design first approach
Always go with the design first approach. First, define the Swagger specification and publish to the Swagger UI after getting it reviewed. The coding should be started after the design is completed and the specification is completed in Swagger.
15 Request format
There are 3 sections in the Request.
15.1. Request headers: This will contain 3 mandatory fields. They are "id", "version" and "requesttime". The "requesttime" have to be in UTC standard ISO8601 format
15.2. Request meta data: This is an optional field. If the service is expecting any metadata, they can be passed here.
15.3. Request payload: This is an optional field. The request payload goes here.
For example,
Request:
16 Response format
There are 4 sections in the Response.
16.1. Response headers: This will contain 3 mandatory fields. They are "id", "version" and "requesttime". The "requesttime" have to be in UTC standard ISO8601 format
16.2. Response meta data: This is an optional field. If the service is expecting any metadata, they can be passed here.
16.3. Response payload: The response payload goes here.
16.4. Errors: The Errors array goes here. Even, in case of single error, the error have to be in an array. This is an optional field. In case if the service doesn't contains error, this element will not be there in the response.
For example,
Response:
In case, there is no request payload or path params or URL params, only the version will be present in the URL.
References
Last updated