8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

A Set of microservices are defined to receive requests from other GovStack-compatible Building Blocks and applications with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

Scheduler must expose its microservices through RESTful API interfaces as defined by OpenAPI v3+ standards. The Scheduler must have any response data payload it returns through its API only in the form of JSON formatted datasets. A summary of the APIS exposed by this Building Block is summarized in the table below. The Scheduler Building Block can be used also as an internal sub-block of another Building Block. In such a case the same services APIs will be used to embed the Scheduler Building Block (without having to pass through the Information Mediator).

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Scheduler Building Block can be found in this GitHub repository.

8.1 Event Management

create a new event, in event_list with given event_details, returns new event id or failure error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created event

Example: event_id:12345

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//event/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

event_id:12345

changes values of specific details (as given by event_details) of given event (selected by event_filter)in event_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

event_idstringRequiredExample: 12345

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//event/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined event in event_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

event_idstringRequiredExample: 12345

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//event HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of events filetered by criteria in event_filter and return info specified by event_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//event/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "event_id": "12345",
      "details": {
        "name": "abc medical camp",
        "description": "medical camp for senior citizens",
        "category": "doctor_consultation",
        "host_entity_id": "67890",
        "from": "2018-02-15T11:00:00",
        "to": "2018-02-15T11:30:00",
        "deadline": "2018-02-15T11:10:00",
        "subscriber_limit": "1",
        "terms": "non refundable",
        "status": "open",
        "venue": {
          "building": "xyz",
          "street": "7th main",
          "area": "wilson garden",
          "city": "bangalore",
          "state": "karnataka",
          "country": "india",
          "lat": "0.001",
          "long": "0.002"
        }
      }
    }
  ]
]

8.2 Entity Management

create a new entity, in entity_list with given entity_details, returns new entity id or entity error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created entity

Example: entity_name:xyz hospital,entity_id:67890

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

entity_name:xyz hospital,entity_id:67890

changes values of specific details (as given by entity_details) of given entity (selected by entity_filter)in entity_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

entity_idstringRequiredExample: 67890

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined entity in entity_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

entity_idstringRequiredExample: 67890

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//entity HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in entity_filter and return info specified by entity_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "entity_id": "67890",
      "details": {
        "category": "hospital",
        "name": "abc",
        "phone": "[phone]",
        "email": "[e-mail]",
        "website": "www.abc.com"
      }
    }
  ]
]

8.3 Alert Schedule Management

create a new alert_schedule, in alert_schedule_list with given alert_schedule_details, returns new alert_schedule id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created alert_schedule

Example: alert_schedule_name:xyz hospital,alert_schedule_id:1

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

alert_schedule_name:xyz hospital,alert_schedule_id:1

changes values of specific details (as given by alert_schedule_details) of given alert_schedule (selected by alert_schedule_filter)in alert_schedule_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

alert_schedule_idstringRequiredExample: 1

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined alert_schedule in alert_schedule_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

alert_schedule_idstringRequiredExample: 1

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in alert_schedule_filter and return info specified by alert_schedule_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "alert_schedule_id": "1",
      "details": {
        "event_id": "12345",
        "target_category": "subscriber",
        "message_id": "1",
        "alert_datetime": "2018-02-15T09:00:00"
      }
    }
  ]
]

8.4 Alert Message Management

create a new message, in message_list with given message_details, returns new message id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created message

Example: message_name:xyz hospital,message_id:1

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//message/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

message_name:xyz hospital,message_id:1

changes values of specific details (as given by message_details) of given message (selected by message_filter)in message_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

message_idstringRequiredExample: 1

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//message/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined message in message_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

message_idstringRequiredExample: 1

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//message HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in message_filter and return info specified by message_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//message/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "message_id": "1",
      "details": {
        "entity_id": "67890",
        "category": "reminder",
        "message_body": "you have doctor consultation today"
      }
    }
  ]
]

8.5 Resource management

create a new resource, in resource_list with given resource_details, returns new resource id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created resource

Example: resource_name:xyz hospital,resource_id:54321

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

resource_name:xyz hospital,resource_id:54321

changes values of specific details (as given by resource_details) of given resource (selected by resource_filter)in resource_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

resource_idstringRequiredExample: 54321

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined resource in resource_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

resource_idstringRequiredExample: 54321

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//resource HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in resource_filter and return info specified by resource_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "resource_id": "54321",
      "details": {
        "name": "psrk",
        "category": "doctor",
        "phone": "[phone]",
        "email": "[e-mail]",
        "alert_url": "[e-mail]",
        "alert_preference": "phone",
        "status_poll_url": "www.doctor1.com"
      }
    }
  ]
]

get details of resources matching criteria given by free_resource_filter, that are free(unallocated) in a given date range and entity and returns success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/availability HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "resource_id": "1",
      "resource_name": "abc",
      "free_slots": [
        "{[2018-02-15T11:00:00to2018-02-15T11:09:00:00],[2018-02-22T11:00:00to2018-02-22T11:17:00:00]}"
      ]
    }
  ]
]

8.6 Subscriber management

create a new subscriber, in subscriber_list with given subscriber_details, returns new subscriber id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created subscriber

Example: subscriber_name:xyz hospital,subscriber_id:12345

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

subscriber_name:xyz hospital,subscriber_id:12345

changes values of specific details (as given by subscriber_details) of given subscriber (selected by subscriber_filter)in subscriber_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

subscriber_idstringRequiredExample: 12345

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined subscriber in subscriber_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

subscriber_idstringRequiredExample: 12345

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in subscriber_filter and return info specified by subscriber_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "subscriber_id": "12345",
      "details": {
        "name": "abc",
        "category": "patient",
        "phone": "[phone]",
        "email": "[e-mail]",
        "alert_url": "www.abc.com",
        "alert_preference": "phone",
        "status_poll_url": "www.abc.com"
      }
    }
  ]
]

8.7 Affiliation management

create a new affiliation, in affiliation_list with given affiliation_details, returns new affiliation id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created affiliation

Example: affiliation_name:xyz hospital,affiliation_id:1

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

affiliation_name:xyz hospital,affiliation_id:1

changes values of specific details (as given by affiliation_details) of given affiliation (selected by affiliation_filter)in affiliation_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

affiliation_idstringRequiredExample: 1

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined affiliation in affiliation_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

affiliation_idstringRequiredExample: 1

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in affiliation_filter and return info specified by affiliation_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "affiliation_id": "1",
      "details": {
        "resource_id": "12345",
        "entity_id": "67890",
        "resource_category": "physician",
        "work_days_hours": [
          {
            "day_of_week": "[monday",
            "start_time": "09:00:00",
            "end_time": "17:00:00"
          }
        ]
      }
    }
  ]
]

8.8 Appointment management

create a new appointment, in appointment_list with given appointment_details, returns new appointment id or failure error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created appointment

Example: [Event_id:12345,appointment_id:1]

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[Event_id:12345,appointment_id:1]

changes values of specific details (as given by appointment_details) of given appointment (selected by appointment_filter)in appointment_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

appointment_idstringRequiredExample: 1

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined appointment in appointment_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

appointment_idstringRequiredExample: 1

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of appointments filetered by criteria in appointment_filter and return info specified by appointment_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "appointment_id": "1",
      "details": {
        "exclusive": "true",
        "event_id": "1",
        "participant_type": "subscriber",
        "participant_id": "12345",
        "status_id": "confirmed",
        "participant_entity_id": "67890"
      }
    }
  ]
]

8.9 Status Logging and Reporting

create a new log, in log_list with given log_details, returns new log id or error code

post

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

application/json

stringOptional

ID of created log

Example: log_name:xyz hospital,log_id:1

post

HTTPcURLJavaScriptPython

POST /r1/eGovStack/COM/11222456/SchedulerBB/creg//log/new HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

log_name:xyz hospital,log_id:1

changes values of specific details (as given by log_details) of given log (selected by log_filter)in log_list and returns success or error code

put

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

log_idstringRequiredExample: 1

qryobjectRequired

Responses

put

HTTPcURLJavaScriptPython

PUT /r1/eGovStack/COM/11222456/SchedulerBB/creg//log/modifications HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

delete a predefined log in log_list and returns success or error code

delete

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

log_idstringRequiredExample: 1

Responses

delete

HTTPcURLJavaScriptPython

DELETE /r1/eGovStack/COM/11222456/SchedulerBB/creg//log HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

No content

get list of entities filetered by criteria in log_filter and return info specified by log_details_required with success or error code

get

Query parameters

requestor_idstringRequiredExample: healthngoadmin1

request_tokenstringRequiredExample: Organizer

qryobjectRequired

Responses

json

object[][]Optional

get

HTTPcURLJavaScriptPython

GET /r1/eGovStack/COM/11222456/SchedulerBB/creg//log/list_details HTTP/1.1
Host: ss2.egovstack.net
Accept: */*

[
  [
    {
      "log_id": "1",
      "details": {
        "logger_role": "resource",
        "logger_id": "1",
        "entity_id": "67890",
        "log_category": "attendance",
        "datetime": "2018-02-15T11:00:00",
        "log_data": "event_id:12345,subscriber_id:1,token:a2s3x2fer,status:attended"
      }
    }
  ]
]

4.10 Information Mediator Interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.11 PubSub Interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.12 Messaging interface

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

4.13 Scheduler Administration

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Scheduler Building Block Specification.

API standards

• The microservice interfaces are defined as per OPENAPI Ver3.0 standards.
• For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.