REST API Guide - mgsystemsllc/chss_prototype GitHub Wiki

Introduction

CHSS prototype is targeted towards development of a cloud based system which supersedes the existing system with additional features and makes it more accessible to users over new age devices.

Purpose

This document defines REST APIs, data set exchange format, authentication method and error codes required while establishing communication between client and server.

Audience

This API guide is intended for client side developers using RESTful interface to access the services available on server.

Overview

The Child Welfare Services prototype REST APIs covers the following features:

Account and User Profile Management
Message Management
HHS Data Management

Account and user profile management allows creation of parent login to the system and creation of a profile to avail of child welfare services. The various services currently available include sending / receiving message from a pre-configured email id and fetching of children’s residential facilities and foster agency details from the server to be displayed on application clients.

The REST APIs support only HTTPS mode.

User Management

Create Account

Description:

This API registers a user and creates a login for accessing the information related to Child Welfare Services rendered by CHHS. This API does not require any authentication to be used for creation of account.

URI:

POST https://server_uri/v1/users

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	username	String	Valid email id of user
	password	String	Password string

Header

  Content-Type: application/json
  Authorization: None

Body

  {
   "json": {
           "username": "EMAIL-ID",
           "password": "PASSWORD"
   }
  }

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error

Login to Account

Description:

This API is used to login to a registered account and access the Child Welfare Services details.

URI:

PUT https://server_uri/v1/users

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	-	-	-

Header

  Content-Type: application/json
  Authorization: Basic

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error

Create Profile

Description:

This API creates a profile of the parent who requires availing child welfare facilities.

URI:

POST https://server_uri/v1/users/profiles

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	first_name	String	User first name
	last_name	String	User last name
	gender	String	User gender: Male/Female
	date_of_birth	String	Date in YYYY-MM-DD format
	marital_status	String	Status: Married, Unmarried, Divorced
	occupation	String	Nature of work
	mobile_number	String	Phone number
	spouse_first_name	String	Spouse first name
	spouse_last_name	String	Spouse last name
	spouse_gender	String	Spouse gender: Male/Female
	spouse_date_of_birth	String	Date in YYYY-MM-DD format
	spouse_occupation	String	Spouse nature of work
	spouse_mobile_number	String	Spouse phone number
	spouse_email	String	Spouse communication email
	address_street	String	User's House / street address
	address_locality	String	User's locality
	address_state	String	User's state
	address_country	String	User's country
	address_zip	String	User's zip code
	count	Integer	Count of children records
	children	Array	Fixed literal for array
	child_first_name	String	Child's first name
	child_last_name	String	Child's last name
	child_gender	String	Child's gender: Male/Female
	child_date_of_birth	String	Date in YYYY-MM-DD

Header

  Content-Type: application/json
  Authorization: Basic

Body

  {
   "json": {
           "first_name": "NAME",
           "last_name": "SURNAME",
  		 "gender": "MALE",
  		 "date_of_birth": "2016-05-26",
  		 "marital_status": "MARRIED",
  		 "occupation": "SERVICE",
  		 "mobile_number": "14082044200",
  		 "spouse_first_name": "NAME",
  		 "spouse_last_name": "SURNAME",
  		 "spouse_gender": "FEMALE",
  		 "spouse_date_of_birth": "2016-05-27",
  		 "spouse_occupation": "SERVICE",
  		 "spouse_mobile_number": "14082044201",
  		 "spouse_email": "[email protected]",
  		 "address_street": "ADDRESS",
  		 "address_locality": "ADDRESS",
  		 "address_state": "STATE",
  		 "address_country": "COUNTRY",
  		 "address_zip": "ZIPCODE",
  		 "count": 1,
  		 "children": [{
  		 "child_first_name": "NAME",
  		 "child_last_name": "SURNAME",
  		 "child_gender": "MALE",
  		 "child_date_of_birth": "2016-05-28"}],
   }
  }

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error

Get Profile

Description:

This API fetches the profile details from the server.

URI:

GET https://server_uri/v1/users/profiles

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	-	-	-

Header

  Content-Type: application/json
  Authorization: Basic

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error
	last_name	String	User last name
	gender	String	User gender: Male/Female
	date_of_birth	String	Date in YYYY-MM-DD format
	marital_status	String	Status: Married, Unmarried, Divorced
	occupation	String	Nature of work
	mobile_number	String	Phone number
	spouse_first_name	String	Spouse first name
	spouse_last_name	String	Spouse last name
	spouse_gender	String	Spouse gender: Male/Female
	spouse_date_of_birth	String	Date in YYYY-MM-DD format
	spouse_occupation	String	Spouse nature of work
	spouse_mobile_number	String	Spouse phone number
	spouse_email	String	Spouse communication email
	address_street	String	User's House / street address
	address_locality	String	User's locality
	address_state	String	User's state
	address_country	String	User's country
	address_zip	String	User's zip code
	count	Integer	Count of children records
	children	Array	Fixed literal for array
	child_first_name	String	Child's first name
	child_last_name	String	Child's last name
	child_gender	String	Child's gender: Male/Female
	child_date_of_birth	String	Date in YYYY-MM-DD

Update Profile

Description:

This API updates a profile of the parent who requires availing child welfare facilities.

URI:

PUT https://server_uri/v1/users/profiles

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	first_name	String	User first name
	last_name	String	User last name
	gender	String	User gender: Male/Female
	date_of_birth	String	Date in YYYY-MM-DD format
	marital_status	String	Status: Married, Unmarried, Divorced
	occupation	String	Nature of work
	mobile_number	String	Phone number
	spouse_first_name	String	Spouse first name
	spouse_last_name	String	Spouse last name
	spouse_gender	String	Spouse gender: Male/Female
	spouse_date_of_birth	String	Date in YYYY-MM-DD format
	spouse_occupation	String	Spouse nature of work
	spouse_mobile_number	String	Spouse phone number
	spouse_email	String	Spouse communication email
	address_street	String	User's House / street address
	address_locality	String	User's locality
	address_state	String	User's state
	address_country	String	User's country
	address_zip	String	User's zip code
	count	Integer	Count of children records
	children	Array	Fixed literal for array
	child_first_name	String	Child's first name
	child_last_name	String	Child's last name
	child_gender	String	Child's gender: Male/Female
	child_date_of_birth	String	Date in YYYY-MM-DD

Header

  Content-Type: application/json
  Authorization: Basic

Body

  {
   "json": {
           "first_name": "NAME",
           "last_name": "SURNAME",
  		 "gender": "MALE",
  		 "date_of_birth": "2016-05-26",
  		 "marital_status": "MARRIED",
  		 "occupation": "SERVICE",
  		 "mobile_number": "14082044200",
  		 "spouse_first_name": "NAME",
  		 "spouse_last_name": "SURNAME",
  		 "spouse_gender": "FEMALE",
  		 "spouse_date_of_birth": "2016-05-27",
  		 "spouse_occupation": "SERVICE",
  		 "spouse_mobile_number": "14082044201",
  		 "spouse_email": "[email protected]",
  		 "address_street": "ADDRESS",
  		 "address_locality": "ADDRESS",
  		 "address_state": "STATE",
  		 "address_country": "COUNTRY",
  		 "address_zip": "ZIPCODE",
  		 "count": 1,
  		 "children": [{
  		 "child_first_name": "NAME",
  		 "child_last_name": "SURNAME",
  		 "child_gender": "MALE",
  		 "child_date_of_birth": "2016-05-28"}],
   }
  }

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error

Message Management

Get Message List

Description:

This API fetches the message headers from the server.

URI:

GET https://server_uri/v1/messages/list?start=1&end=10

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	start	Integer	Starting message Id
	end	Integer	Ending message Id
Request Body	-	-	-

Header

  Content-Type: application/json
  Authorization: Basic

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error
	count	Integer	Message count
	messages	Array	Fixed literal for array
	message_id	String	ID of message on server
	message_header	String	Holds Time, From and Subject details

Get Message Details

Description:

This API fetches the complete message based on message id from server.

URI:

GET https://server_uri/v1/messages/:message_id

Request:

Category	Parameter	Type	Description
Uri	message_id	String	ID of message to be retrieved
Query String	-	-	-
Request Body	-	-	-

Header

  Content-Type: application/json
  Authorization: Basic

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error
	message_id	String	ID of message on server
	message_body	String	Message data

Send Message

Description:

This API posts a message to server to be forwarded to service network.

URI:

POST https://server_uri/v1/messages/send

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	subject	String	Message subject
	message	String	Message body

Header

  Content-Type: application/json
  Authorization: Basic

Body

  {
   "json": {
           "subject": "Message Subject",
           "message": "Message Body"
   }
  }

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error

HHS Data Management

Get Children's Facility Details

Description:

This API fetches the children’s facilities and foster agency details from server.

URI:

GET https://server_uri/v1/facilities

Request:

Category	Parameter	Type	Description
Uri	-	-	-
Query String	-	-	-
Request Body	-	-	-

Header

  Content-Type: application/json
  Authorization: None

Response:

Category	Parameter	Type	Description
Response Body	result	String	Message string provides success or error
	count	Integer	Count of records
	facilities	Array	Fixed literal
	facility_name	String	Name of facility
	facility_type	String	Type of facility
	facility_number	String	Facility number
	facility_admin	String	Facility admin name
	facility_phone	String	Facility phone number
	facility_address	String	Facility address
	facility_city	String	Facility city name
	facility_state	String	Facility state name
	facility_zip	String	Facility zip code

Appendix

RESTAPI Response Format

Success Response

	{
	  "json": {
		"result": "ok",
		"param1": "value1",
		"param2": "value2",
		"array": [
		  {
			"param3": "value3"
		  },
		  {
			"param4": "value4"
		  }
		]
	  }
	}

Error Response

	{
	  "json": {
		"result": "error",
		"message": "message content"
	  }
	}

HTTP Error Code

S.No.	Error Response Code	Error Message	Description
1.	200	OK	For Success
2.	201	Created	For POST request success
3.	400	Bad Request	Incorrect URL" or "Route is not exist"
4.	401	Unauthorized	Invalid Credentials
5.	403	Forbidden	Not authorized to perform requested operation
6.	412	Pre-condition	Precondition failure where expected values are not coming with request
7.	500	Internal Server Error	API call failed on application level