Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] Get Person details [API-005-010-006-0204]
Guideline ID	GUI-0011
Author	@Viacheslav Tybin (SoE eHealth)
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-005-010-006-0204
Microservices (namespace)	IL
Component	Patient Cabinet
Component ID	COM-005-010
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-patient-cabinet/cabinet/get-person-details
Resource	{{host}}/api/cabinet/persons/details
Scope	person:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This WS is designed to get person details in a cabinet. Every patient can obtain only it's own details.

Logic

N/A

Configuration parameters

N/A

Dictionaries

GENDER
DOCUMENT_TYPE
ADDRESS_TYPE
COUNTRY
SETTLEMENT_TYPE
STREET_TYPE
PHONE_TYPE
AUTHENTICATION_METHOD
PREFERRED_WAY_COMMUNICATION

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1
2

Request structure

See on API-specification

Headers

Request data validation

Validate token

Check token existance
- in case error return 404 - token was not found
Check expiration date tokens.expires_at
- if tokens.expires_at < now() return 401 - access denied
Extract party_user (user_id) from token
Check user scopes in order to perform this action (scope = ''person:read")
1. Return 403 in case invalid scope(s) - "Your scope does not allow to access this resource. Missing allowances: "person:read"

Validate role

Check users_roles.user_id=&.user and user_roles.role_id = roles.id where roles.name = CABINET
- in case error return 403

Validate person

Check if mithril.users.person_id = mpi.persons.id and mithril.users.tax_id = mpi.persons.tax_id
- in case error return 401
Check if users.is_blocked = false
- in case error return 401
Check users password is not expired
- in case error return 401 - password expired

Processing

In case nothing found return 404 - user was not found

json schema

Response structure examples

See on API-specification

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "first_name": "Петро",
    "last_name": "Іванов",
    "second_name": "Миколайович",
    "birth_date": "1991-08-19",
    "birth_country": "Україна",
    "birth_settlement": "Вінниця",
    "gender": "MALE",
    "email": "email@example.com",
    "tax_id": "3126509816",
    "secret": "secret",
    "documents": [
      {
        "type": "PASSPORT",
        "number": "АА120518",
        "expiration_date": "2021-02-28",
        "issued_by": "Рокитнянським РВ ГУ МВС Київської області",
        "issued_at": "2017-02-28"
      }
    ],
    "addresses": [
      {
        "type": "RESIDENCE",
        "country": "UA",
        "area": "Житомирська",
        "region": "Бердичівський",
        "settlement": "Київ",
        "settlement_type": "CITY",
        "settlement_id": "b075f148",
        "street_type": "STREET",
        "street": "вул. Ніжинська",
        "building": "15",
        "apartment": "23",
        "zip": "02090"
      }
    ],
    "phones": [
      {
        "type": "MOBILE",
        "number": "+380503410870"
      }
    ],
    "authentication_methods": [
      {
        "type": "OTP",
        "phone_number": "+38093*****85"
      }
    ],
    "preferred_way_communication": "email",
    "unzr": "19900101-00099",
    "emergency_contact": {
      "first_name": "Петро",
      "last_name": "Іванов",
      "second_name": "Миколайович",
      "phones": [
        {
          "type": "MOBILE",
          "number": "+380503410870"
        }
      ]
    },
    "process_disclosure_data_consent": true
  },
  "id": "7e9cffd9-c75f-45fb-badf-6e8d20b6a8a8"
}

HTTP status codes

	Response code	HTTP Status code	Message	Internal name	Description

	Response code	HTTP Status code	Message	Internal name	Description
1	Базові
2		200	Response
3		401	Access denied	Validation failed
4		401	Password expired	Validation failed
5		403	Your scope does not allow to access this resource. Missing allowances: "person:read"	Validation failed
6		404	Token was not found	Validation failed
7		404	User was not found	Validation failed
8	Специфічні
9

Post-processing processes

N/A

Technical modules where the method is used

Название	ID ТМ	Статус

Название	ID ТМ	Статус
RC-V.2.1 [TM-011] Відхилення ЕР фармацевтом	TM0112
RC-V.2.1 [TM-011] Відхилення ЕР фармацевтом

[DRAFT] Get Person details [API-005-010-006-0204]

Properties of a REST API method document

Purpose

Logic

Configuration parameters

Dictionaries

Input parameters

Request structure

Headers

Request data validation

Validate token

Validate role

Validate person

Processing

Response structure examples

HTTP status codes

Post-processing processes

Technical modules where the method is used