Resources and Endpoints
=======================


Tasks
-----

Tasks encapsulate individual invocations of a task service made per release.
The Release Coordinator will create new tasks for each enabled service during
the creation of a new release and will follow up with each service throughout
the lifetime of the task.

.. http:get:: /tasks

    Returns a list of tasks

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by
    :query release: Filter tasks related to a given release's kf_id
    :query task_service: Filter tasks related to a given task service's kf_id
    :query state: Filter tasks by a given state

    **Example**:

    .. http:example:: curl

       GET /tasks?release=RE_C6PTRN2K&task_service=TS_WPEKCZHQ HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "count": 1,
           "next": null,
           "previous": null,
           "results": [
               {
                   "kf_id": "TA_WAAE3ZBN",
                   "state": "canceled",
                   "progress": 0,
                   "release": "https://kf-release-coord.kidsfirstdrc.org/releases/RE_C6PTRN2K",
                   "task_service": "https://kf-release-coord.kidsfirstdrc.org/task-services/TS_WPEKCZHQ",
                   "created_at": "2018-09-13T19:48:49.467518Z",
                   "service_name": "Portal ETL Task Service"
               }
           ]
       }


.. http:patch:: /tasks/(kf_id)

    Updates a task of ``kf_id`` with state or progress.
    Use by task services to report progress or status of one of the tasks.

    :<json string state: The state of the task
    :<json int progress: The percentage of completion of the task

    **Example**:

    .. http:example:: curl

       PATCH /tasks/TA_WAAE3ZBN HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "state": "staged",
           "progress": 100
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "TA_WAAE3ZBN",
           "state": "staged",
           "progress": 100,
           "release": "https://kf-release-coord.kidsfirstdrc.org/releases/RE_C6PTRN2K",
           "task_service": "https://kf-release-coord.kidsfirstdrc.org/task-services/TS_WPEKCZHQ",
           "created_at": "2018-09-13T19:48:49.467518Z",
           "service_name": "Portal ETL Task Service"
       }


Task Services
-------------

Task Services are services that perform an action that is required during a
release.
Task Services are required to expose a consistent interface to the tasks that
they have been assigned by the Release Coordinator so that the Release
Coordinator may provide an accurate view into the overall state of a release.

.. http:get:: /task-services

    Lists task services.

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by
    :query enabled: Filter by whether a task service is enabled or not.
        ``True`` or ``False``.

    **Example**:

    .. http:example:: curl

       GET /task-services?enabled=False HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "count": 1,
            "next": null,
            "previous": null,
            "results": [
                {
                    "kf_id": "TS_P4QEPHZT",
                    "name": "Snapshot Task Service",
                    "description": "The snapshot task service creates a data dump directly against the data service, given a specific version of data release. The data snapshot is available via Amazon S3 in a JSON form.",
                    "last_ok_status": 0,
                    "author": "meen",
                    "health_status": "ok",
                    "url": "http://kf-task-snapshot",
                    "created_at": "2018-09-11T15:23:46.922950Z",
                    "enabled": false
                }
            ]
        }

.. http:get:: /task-services/(kf_id)

    Get task service of ``kf_id``.

    **Example**:

    .. http:example:: curl

       GET /task-services/TS_WPEKCZHQ HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "TS_WPEKCZHQ",
           "name": "Portal ETL Task Service",
           "description": "Run ETL to update ES indexes with latest data from Data Service.",
           "last_ok_status": 0,
           "author": "jon",
           "health_status": "ok",
           "url": "http://etl-task-service-prd",
           "created_at": "2018-09-13T17:00:09.859959Z",
           "enabled": true
       }


.. http:post:: /task-services

    Register a new task service.
    The coordinator will attempt to ping the ``/status`` endpoint on the
    provided url to verify that the task service can be reached. If there
    is no response, or an error trying to get a response, the task service
    will not be registered and the response will respond with a 400.

    :<json string name: The name of the new task service.
    :<json string description: The description of the new task service.
    :<json string autho: The author of the task service.
    :<json string url: The url of the task service.

    **Example**:

    .. http:example:: curl

       POST /task-services HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "name": "Portal ETL Task Service",
           "description": "Run ETL to update ES indexes with latest data from Data Service.",
           "author": "jon",
           "url": "http://etl-task-service-prd"
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "TS_WPEKCZHQ",
           "name": "Portal ETL Task Service",
           "description": "Run ETL to update ES indexes with latest data from Data Service.",
           "last_ok_status": 0,
           "author": "jon",
           "health_status": "ok",
           "url": "http://etl-task-service-prd",
           "created_at": "2018-09-13T17:00:09.859959Z",
           "enabled": true
       }


.. http:patch:: /task-services

    Updates a task service of ``kf_id``.

    :<json string name: The name of the new task service.
    :<json string description: The description of the new task service.
    :<json string autho: The author of the task service.
    :<json string url: The url of the task service.

    **Example**:

    .. http:example:: curl

       PATCH /task-services/TS_WPEKCZHQ HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "name": "Portal ETL Task Service",
           "description": "Run ETL to update ES indexes with latest data from Data Service.",
           "author": "jon",
           "url": "http://etl-task-service-prd"
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "TS_WPEKCZHQ",
           "name": "Portal ETL Task Service",
           "description": "Run ETL to update ES indexes with latest data from Data Service.",
           "last_ok_status": 0,
           "author": "jon",
           "health_status": "ok",
           "url": "http://etl-task-service-prd",
           "created_at": "2018-09-13T17:00:09.859959Z",
           "enabled": true
       }


.. http:delete:: /task-services/(kf_id)

    Deletes a task service of ``kf_id``.

    **Example**:

    .. http:example:: curl

       DELETE /task-services/TS_WPEKCZHQ HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept


Releases
--------


.. http:get:: /releases

    Lists releases.

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by
    :query state: Filter tasks by a given state

    **Example**:

    .. http:example:: curl

       GET /releases?state=published HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "count": 1,
            "next": "http://kf-release-coord-dev.kidsfirstdrc.org/releases?state=published",
            "previous": null,
            "results": [
                {
                    "kf_id": "RE_EJTE6XDS",
                    "name": "Test Auth",
                    "description": "",
                    "notes": [],
                    "state": "published",
                    "studies": [
                        "SD_ME0WME0W"
                    ],
                    "tasks": [
                        {
                            "kf_id": "TA_T4D9PMPJ",
                            "state": "published",
                            "progress": 0,
                            "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_EJTE6XDS",
                            "task_service": "http://kf-release-coord-dev.kidsfirstdrc.org/task-services/TS_8DSD3XHF",
                            "created_at": "2018-11-07T16:32:43.563546Z",
                            "service_name": "Reports Task Service"
                        }
                    ],
                    "version": "0.7.0",
                    "created_at": "2018-11-07T16:32:43.271141Z",
                    "tags": [],
                    "author": "daniel",
                    "is_major": false
                }
            ]
        }


.. http:get:: /releases/(kf_id)

    Gets a release of ``kf_id``.

    **Example**:

    .. http:example:: curl

       GET /releases/RE_EJTE6XDS HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RE_EJTE6XDS",
           "name": "Test Auth",
           "description": "",
           "notes": [],
           "state": "published",
           "studies": [
               "SD_ME0WME0W"
           ],
           "tasks": [
               {
                   "kf_id": "TA_T4D9PMPJ",
                   "state": "published",
                   "progress": 0,
                   "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_EJTE6XDS",
                   "task_service": "http://kf-release-coord-dev.kidsfirstdrc.org/task-services/TS_8DSD3XHF",
                   "created_at": "2018-11-07T16:32:43.563546Z",
                   "service_name": "Reports Task Service"
               }
           ],
           "version": "0.7.0",
           "created_at": "2018-11-07T16:32:43.271141Z",
           "tags": [],
           "author": "daniel",
           "is_major": false
       }


.. http:post:: /releases

    Start a new release.
    This will begin a release by creating new tasks for each service.

    :<json string name: The name of the new release.
    :<json string description: The description of the new release.
    :<json boolean is_major: Whether the release is major or not.
    :<json string author: The author of the release.
    :<json array studies: An array of study ``kf_id`` s to include in the
       release

    **Example**:

    .. http:example:: curl

       PATCH /releases/RE_EJTE6XDS HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "name": "My Release",
           "description": "New description,
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RE_EJTE6XDS",
           "name": "My Release",
           "description": "New description",
           "notes": [],
           "state": "published",
           "studies": [
               "SD_ME0WME0W"
           ],
           "tasks": [
               {
                   "kf_id": "TA_T4D9PMPJ",
                   "state": "published",
                   "progress": 0,
                   "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_EJTE6XDS",
                   "task_service": "http://kf-release-coord-dev.kidsfirstdrc.org/task-services/TS_8DSD3XHF",
                   "created_at": "2018-11-07T16:32:43.563546Z",
                   "service_name": "Reports Task Service"
               }
           ],
           "version": "0.7.0",
           "created_at": "2018-11-07T16:32:43.271141Z",
           "tags": [],
           "author": "daniel",
           "is_major": false
       }


.. http:patch:: /releases/(kf_id)

    Update a release of ``kf_id``.

    **Example**:

    .. http:example:: curl

       PATCH /releases/RE_EJTE6XDS HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "name": "My Release",
           "description": "New description,
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RE_EJTE6XDS",
           "name": "My Release",
           "description": "New description",
           "notes": [],
           "state": "published",
           "studies": [
               "SD_ME0WME0W"
           ],
           "tasks": [
               {
                   "kf_id": "TA_T4D9PMPJ",
                   "state": "published",
                   "progress": 0,
                   "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_EJTE6XDS",
                   "task_service": "http://kf-release-coord-dev.kidsfirstdrc.org/task-services/TS_8DSD3XHF",
                   "created_at": "2018-11-07T16:32:43.563546Z",
                   "service_name": "Reports Task Service"
               }
           ],
           "version": "0.7.0",
           "created_at": "2018-11-07T16:32:43.271141Z",
           "tags": [],
           "author": "daniel",
           "is_major": false
       }


.. http:delete:: /releases/(kf_id)

    Cancels a release of ``kf_id``.

    **Example**:

    .. http:example:: curl

       DELETE /releases/RE_EJTE6XDS HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RE_EJTE6XDS",
           "name": "Test Auth",
           "description": "",
           "notes": [],
           "state": "canceling",
           "studies": [
               "SD_ME0WME0W"
           ],
           "tasks": [
               {
                   "kf_id": "TA_T4D9PMPJ",
                   "state": "published",
                   "progress": 0,
                   "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_EJTE6XDS",
                   "task_service": "http://kf-release-coord-dev.kidsfirstdrc.org/task-services/TS_8DSD3XHF",
                   "created_at": "2018-11-07T16:32:43.563546Z",
                   "service_name": "Reports Task Service"
               }
           ],
           "version": "0.7.0",
           "created_at": "2018-11-07T16:32:43.271141Z",
           "tags": [],
           "author": "daniel",
           "is_major": false
       }


.. http:post:: /releases/(kf_id)/publish

    Start publishing release of ``kf_id``.
    The release must be in the ``staged`` state.

    **Example**:

    .. http:example:: curl

       PATCH /releases/RE_EJTE6XDS/publish HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "message": "publishing"
       }


Release Notes
-------------

Release notes describe changes made in a release. They may optionally target
a specific study to allow individual studies to be annotated separately.


.. http:get:: /release-notes

    Returns a list of release notes

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by
    :query release: Filter tasks related to a given release's kf_id
    :query study: Filter tasks related to a given study's kf_id

    **Example**:

    .. http:example:: curl

       GET /release-notes?author=&study=SD_ME0WME0W HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "count": 1,
            "next": null,
            "previous": null,
            "results": [
                {
                    "kf_id": "RN_D1HXSBVD",
                    "description": "Probably need more cats",
                    "author": "daniel",
                    "created_at": "2018-10-25T20:06:22.936504Z",
                    "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_GD2D17A9",
                    "study": "http://kf-release-coord-dev.kidsfirstdrc.org/studies/SD_ME0WME0W"
                }
            ]
        }


.. http:get:: /release-notes/(kf_id)

    Get a specific note of ``kf_id``.


    **Example**:

    .. http:example:: curl

       GET /release-notes/RN_D1HXSBVD HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RN_D1HXSBVD",
           "description": "Probably need more cats",
           "author": "daniel",
           "created_at": "2018-10-25T20:06:22.936504Z",
           "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_GD2D17A9",
           "study": "http://kf-release-coord-dev.kidsfirstdrc.org/studies/SD_ME0WME0W"
       }


.. http:post:: /release-notes

    Create a new note for a release. May optionally specify a study in the
    release.

    :<json string description: The description of changes in the release
    :<json string author: The author of the note
    :<json string release: The kf_id of the release that the note describes
    :<json string study: The kf_id of a study that the note describes


    **Example**:

    .. http:example:: curl

       POST /release-notes HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "description": "Probably need more cats",
           "author": "daniel",
           "release": "RE_GD2D17A9",
           "study": "SD_ME0WME0W"
       }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "count": 1,
            "next": null,
            "previous": null,
            "results": [
                {
                    "kf_id": "RN_D1HXSBVD",
                    "description": "Probably need more cats",
                    "author": "daniel",
                    "created_at": "2018-10-25T20:06:22.936504Z",
                    "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_GD2D17A9",
                    "study": "http://kf-release-coord-dev.kidsfirstdrc.org/studies/SD_ME0WME0W"
                }
            ]
        }


.. http:patch:: /release-notes/(kf_id)

    Update a specific note of ``kf_id``.

    :<json string description: The description of changes in the release
    :<json string author: The author of the note
    :<json string release: The kf_id of the release that the note describes
    :<json string study: The kf_id of a study that the note describes

    **Example**:

    .. http:example:: curl

       PATCH /release-notes/RN_D1HXSBVD HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
           "description": "New description"
       }

       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "kf_id": "RN_D1HXSBVD",
           "description": "New description",
           "author": "daniel",
           "created_at": "2018-10-25T20:06:22.936504Z",
           "release": "http://kf-release-coord-dev.kidsfirstdrc.org/releases/RE_GD2D17A9",
           "study": "http://kf-release-coord-dev.kidsfirstdrc.org/studies/SD_ME0WME0W"
       }


.. http:delete:: /release-notes/(kf_id)

    Delete a release note of ``kf_id``.

    **Example**:

    .. http:example:: curl

       DELETE /release-notes/RN_D1HXSBVD HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept


Events
------

Events are created when tasks and releases change between states.
They are used to log status changes and history of releases for
debugging and notification purposes.

.. http:get:: /events

    Lists events.

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by
    :query release: Filter events related to a given release's kf_id
    :query study: Filter events related to a given study's kf_id
    :query task: Filter events related to a given task's kf_id
    :query task_service: Filter events related to a given task's kf_id

    **Example**:

    .. http:example:: curl

       GET /events?release=RE_N06RZ4VV HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "count": 1,
           "next": "null",
           "previous": null,
           "results": [
               {
                   "kf_id": "TA_YPK2CS52",
                   "event_type": "info",
                   "message": "release RE_N06RZ4VV, version 3.35.0 changed from publishing to published",
                   "release": "https://kf-release-coord.kidsfirstdrc.org/releases/RE_N06RZ4VV",
                   "task_service": null,
                   "task": null,
                   "created_at": "2019-07-30T18:03:54.308385Z"
               }
           ]
       }


.. http:post:: /events

    Creates a new event

    :<json string event_type: The type of event
    :<json string message: A message describing the event
    :<json string release: The ``kf_id`` of the releated release
    :<json string study: The ``kf_id`` of the releated release
    :<json string task: The ``kf_id`` of the releated release
    :<json string task_service: The ``kf_id`` of the releated release

    **Example**:

    .. http:example:: curl

       POST /events HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json

       {
            "event_type": "info",
            "message": "release RE_N06RZ4VV, version 3.35.0 changed from publishing to published",
            "release": "RE_N06RZ4VV"
        }


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "kf_id": "TA_YPK2CS52",
            "event_type": "info",
            "message": "release RE_N06RZ4VV, version 3.35.0 changed from publishing to published",
            "release": "https://kf-release-coord.kidsfirstdrc.org/releases/RE_N06RZ4VV",
            "task_service": null,
            "task": null,
            "created_at": "2019-07-30T18:03:54.308385Z"
        }


.. http:get:: /events/(kf_id)

    Gets an event of ``kf_id``.

    **Example**:

    .. http:example:: curl

       GET /events/TA_YPK2CS52 HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
            "kf_id": "TA_YPK2CS52",
            "event_type": "info",
            "message": "release RE_N06RZ4VV, version 3.35.0 changed from publishing to published",
            "release": "https://kf-release-coord.kidsfirstdrc.org/releases/RE_N06RZ4VV",
            "task_service": null,
            "task": null,
            "created_at": "2019-07-30T18:03:54.308385Z"
        }


.. http:delete:: /events/(kf_id)

    Delete an event of ``kf_id``.

    **Example**:

    .. http:example:: curl

       DELETE /events/TA_YPK2CS52 HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept


Studies
-------

Studies are mirrored from the dataservice and are immutable from the Release
Coordinator.
They are only used to relate releases together to create timelines for given
studies.


.. http:get:: /studies

    Returns a list of studies.

    :query limit: Number of results to return in a page, defaults to 10
    :query offset: How many items to offset the page by

    **Example**:

    .. http:example:: curl

       GET /studies HTTP/1.1
       Host: kf-release-coord.kidsfirstdrc.org
       Accept: application/json


       HTTP/1.1 200 OK
       Allow: GET, POST, HEAD, OPTIONS
       Content-Type: application/json
       Vary: Accept

       {
           "count": 1,
           "next": null,
           "previous": null,
           "results": [
               {
                   "kf_id": "SD_1P41Z782",
                   "name": "OpenDIPG: ICR London",
                   "version": "3.35.0",
                   "visible": true,
                   "last_pub_version": "3.35.0",
                   "last_pub_date": "2019-07-30T17:40:45.715939Z",
                   "deleted": false,
                   "created_at": "2019-07-29T14:29:07.227936Z"
               }
           ]
       }