MOSIP Docs 1.1.5
GitHubCommunityTech Blogs
  • Home
  • Architecture
    • Guiding Principles
    • MOSIP Architecture
      • Technology Stack
    • MOSIP and Data
      • Naming Standards
      • Data-Model
    • Privacy & Security
      • Cryptography in MOSIP
    • Anonymous Profiling Support
  • Modules
    • Pre-Registration
      • Pre-Registration Functionality
      • UI Specification for Pre-registration
      • Pre-Registration Configuration
    • Registration
      • Registration Functionality
      • Registration Packet
      • Registration Client Setup
      • First User Registration and Onboarding
      • Guide to Configure MOSIP for Biometrics
      • Guide to On-board Biometric Devices
      • Device Integration Specifications
      • UI Specification for Registration Client
    • Registration Processor
      • Registration Processor Functionality
      • Deduplication and Manual Adjudication
      • MOSIP ID Object Definition
    • ID Repository
    • ID Authentication
      • ID Authentication Functionality
    • Resident Services
      • Resident Services Functionality
    • Partner Management
      • Partner Management Functionality
      • MOSIP Partner Secure Communication
      • Partner Self Service Portal
    • Administration
      • Admin Services Functionality
      • Download Card
    • Kernel
      • Audit Manager Functionality
        • Admin Service Audits
        • Resident Service Audits
        • Partner Management Audits
        • Registration Client Audits
        • Registration Processor Audits
        • ID Repository Audits
        • ID Authentication Audits
        • Pre-registration Audits
      • Authentication and Authorization Functionality
      • Auth Adapter
      • Auth Implementation
      • Common Services Functionality
      • Data Services Functionality
      • Master Data Services Functionality
      • UIN and VID Generation Service Functionality
      • VID Generator
  • Biometrics
    • ABIS
    • Biometric SDK
    • MDS Specification
    • Biometric Specification
    • CBEFF XML
    • Compliance Tool Kit
  • Build & Deploy
    • Sandbox Installer
    • Deployment Architectures
    • Cell Based Deployment Architecture
    • Hardware Security Module HSM Specifications
    • Hardware Sizing
    • Customizations for a Country
    • Other Installation Guides
      • Steps to Install and Configure HDFS
      • Steps to Install and use PostgreSQL Version 10.2 on RHEL 7.5
      • Steps to Install Clam AntiVirus Version 0.101.0
      • Steps to Install Keycloak Standalone Server
    • Services in MOSIP
  • Glossary
  • Contribute
    • Call for Contribution
    • Contributor's Guide
    • Code of Conduct
    • Issue Reporting Guideline
    • Coding Standards
      • Auth Angular User Guide
      • Auth SpringBoot User Guide
      • Gitub Workflow
      • MOSIP Java Coding Standards
      • MOSIP REST API guidelines
      • Registration Client UI Developer Document
      • Registration Client Developer Documentation
      • Security Tools
    • Testing
      • Test Rig Design
      • Tester Documentation
      • Testing Attachments Kernel
  • APIs
    • ABIS APIs
    • Admin APIs
    • AuthN and AuthZ APIs
    • Biometric SDK APIs
    • BlacklistedWords APIs
    • Common APIs
    • Device APIs
    • Device Type and Subtype APIs
    • Device Management APIs
    • Document APIs
    • Dynamic Fields APIs
    • Holiday APIs
    • ID Authentication APIs
    • ID Repository APIs
    • ID Schema APIs
    • Kernel APIs
    • Machine APIs
    • Master Data Biometric APIs
    • Packet APIs
    • Packet Manager APIs
    • Partner Management Service APIs
    • Pre Registration APIs
    • Registration Center APIs
    • Registration Processor APIs
    • Resident Service APIs
    • Sync Data APIs
    • Template APIs
    • Zone APIs
  • Older Releases
    • Release Notes 1.1.5
      • Enhancements
      • Defect Fixes
      • Patches
        • Patch 1.1.5.5
        • Patch 1.1.5.5-P1
    • Release Notes 1.1.4
      • Enhancements
      • Defect Fixes
    • Release Notes 1.1.3
      • Features
      • Bug Fixes
    • Release Notes 1.1.2
      • Features
      • Bug Fixes
    • Release Notes 1.1.1
      • Bug Fixes
      • Artifact Version
    • Release Notes 1.1.0
      • Features
      • Bug Fixes
      • 1.2.0 Features
      • Artifact Version
    • Release Notes 1.0.6
    • Release Notes 1.0.5
    • Release Notes 1.0.0
      • Features
    • Release Notes 0.9.0
  • Roadmap
    • Roadmap Activities
  • Revision History
  • License
Powered by GitBook
On this page
  • 1 Introduction
  • 1.1 Context
  • 1.2 Purpose of this document
  • 1.3 Scope of this document
  • 2 URL structure
  • 2.1 General structure
  • 3 Resources - Usage of nouns and verbs
  • 4 Resources – Usage of plurals in nouns
  • 5 Resources – actions in the URL
  • 6 Appropriate usage of the HTTP methods
  • 7 HTTP Status codes
  • 8 Identifying a resource
  • 9 Filtering
  • 10 Sorting
  • 11 Pagination
  • 12 Always use SSL
  • 13 Versioning
  • 14 Design first approach
  • 15 Request format
  • 16 Response format
  • References

Was this helpful?

Export as PDF
  1. Contribute
  2. Coding Standards

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:

{
	/***** Following is the header information *****/
	"id":"mosip.kernel.otpservice",			
	"version":"1.0",	
	"requesttime":"2007-12-03T10:15:30Z",
	
	/***** Following is the metadata information *****/
	"metadata" : {
	},
	
	/***** Following is the request payload *****/
	"request" : {
		// payload
	}
}

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:

{

	/***** Following is the header information *****/
	"id":"mosip.kernel.otpservice",			
	"version":"1.0",	
	"responsetime":"2007-12-03T10:15:30Z",	

	/***** Following is the metadata information *****/
	"metadata" : {
		"status" : "error"
	},
	
	/***** Following is the response payload *****/
	"response" : {
		// payload
	}

	/***** Errors wrapped in an array *****/
	"errors":[
		"errorCode": "PRG_PAM_APP_001",
		"message": "Mobile or email not available"
	  },
  	  {
		"errorCode": "PRG_PAM_APP_001",
		"message": "Service vendor is not responding"
	  }		
	]
}

In case, there is no request payload or path params or URL params, only the version will be present in the URL.

References

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9

https://restfulapi.net/resource-naming/
PreviousMOSIP Java Coding StandardsNextRegistration Client UI Developer Document

Last updated 3 years ago

Was this helpful?