Skip to content
Snippets Groups Projects
Commit 3579cf30 authored by James Graham's avatar James Graham
Browse files

Ensure that API endpoints in docs match API

parent e92f9a84
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/source/ref_applications_api.rst
+ 364
− 68
View file @ 3579cf30
...@@ -17,8 +17,8 @@ Overview ...@@ -17,8 +17,8 @@ Overview
This document provides a schema reference to the PEDASI Applications API which is used by third-party applications to request data, metadata, or provenance records from a PEDASI instance and its data sources. This document provides a schema reference to the PEDASI Applications API which is used by third-party applications to request data, metadata, or provenance records from a PEDASI instance and its data sources.
API Endpoints API Endpoints - General
------------- -----------------------
-------- --------
...@@ -63,17 +63,17 @@ Response class (Status 200): application/json ...@@ -63,17 +63,17 @@ Response class (Status 200): application/json
Responses messages: Responses messages:
.. list-table:: .. list-table::
:widths: 16 80 16 :widths: 16 80 16 16
:header-rows: 1 :header-rows: 1
* - HTTP Status Code * - HTTP Status Code
- Reason
- Response - Response
- Reason
- Response Type - Response Type
* - * - 200
- - List of data sources
- - Successful
- application/json - application/json
-------- --------
...@@ -124,38 +124,39 @@ Response class (Status 200): application/json ...@@ -124,38 +124,39 @@ Response class (Status 200): application/json
} }
] ]
} }
--------
GET /api/datasources/{datasource_id}/metadata/ Responses messages:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Implementation notes:
Retrieves metadata for a given data source which may include an API query to the data source, if supported by the data source. The authenticated user must have META permissions or above to access the data source. In the general case, this is implementation-specific for the data connector, in the case of a HyperCat catalogue, it presents the catalogue record for that dataset.
Parameters:
.. list-table:: .. list-table::
:widths: 16 80 16 :widths: 16 80 16 16
:header-rows: 1 :header-rows: 1
* - Parameter * - HTTP Status Code
- Description - Response
- Type - Reason
- Response Type
* - datasource_id * - 200
- The numeric id of the data source - Single data source
- integer - Successful
- application/json
Response class (Status 200): application/json * - 404
.. code-block:: json - .. code-block:: json
{
"detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
-------- --------
GET /api/datasources/{datasource_id}/datasets/ GET /api/datasources/{datasource_id}/metadata/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Implementation notes: Implementation notes:
Retrieves the list of dataset IDs within a catalogue, which may be via an API query to the data source, if supported by the data source. The authenticated user must have META permissions or above to access the data source. In the general case, this is implementation-specific for the data connector. Retrieves metadata for a given data source which may include an API query to the data source, if supported by the data source. The authenticated user must have META permissions or above to access the data source. In the general case, this is implementation-specific for the data connector, in the case of a HyperCat catalogue, it presents the catalogue record for that dataset.
Parameters: Parameters:
.. list-table:: .. list-table::
...@@ -171,35 +172,48 @@ Parameters: ...@@ -171,35 +172,48 @@ Parameters:
- integer - integer
Response class (Status 200): application/json Response class (Status 200): application/json
.. code-block:: json Dependent on data source
-------- Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
GET /api/datasources/{datasource_id}/metadata/{dataset_id}/ * - HTTP Status Code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Response
- Reason
- Response Type
Implementation notes: * - 200
Specific to data sources which purport to act as catalogues of data, it retrieves metadata for a single dataset contained within the given data source in most cases via an API query to the data source (e.g. HyperCat), although is dependent on data connector implementation. The authenticated user must have permission to use the given data source. - Data source metadata
- Successful
- application/json
Parameters: * - 400
.. list-table:: - .. code-block:: json
:widths: 16 80 16
:header-rows: 1
* - Parameter {
- Description "status": "error",
- Type "message": "Data source does not provide metadata"
}
* - datasource_id - Data source/connector does not support metadata queries
- The numeric id of the data source - application/json
- integer
* - dataset_id * - 404
- The id of the data set within the specific data source, which may be a URI - .. code-block:: json
- string
Response class (Status 200): application/json {
Dependent on data source "detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
* - any other
- Error response from external data source
- An error occured within the external data source
- determined by data source
-------- --------
...@@ -229,33 +243,46 @@ Parameters: ...@@ -229,33 +243,46 @@ Parameters:
Response class (Status 200): type-specific to datasource Response class (Status 200): type-specific to datasource
Dependent on data source Dependent on data source
-------- Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
GET /api/datasources/{datasource_id}/data/{dataset_id}/ * - HTTP Status Code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Response
- Reason
- Response Type
Implementation notes: * - 200
In the case where a data source represents a catalogue of datasets, retrieve a single dataset via an API query to the data source. The authenticated user must have permission to use the given data source. - Data source data
- Successful
- determined by data source
Parameters: * - 400
.. list-table:: - .. code-block:: json
:widths: 16 80 16
:header-rows: 1
* - Parameter {
- Description "status": "error",
- Type "message": "Data source does not provide data"
}
* - datasource_id - Data source/connector does not support data queries
- The numeric id of the data source - application/json
- integer
* - dataset_id * - 404
- The id of the data set within the specific data source, which may be a URI - .. code-block:: json
- string
Response class (Status 200): type-specific to datasource {
Dependent on data source "detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
* - any other
- Error response from external data source
- An error occured within the external data source
- determined by data source
-------- --------
...@@ -324,8 +351,277 @@ Response class (Status 200): application/json ...@@ -324,8 +351,277 @@ Response class (Status 200): application/json
] ]
} }
Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
* - HTTP Status Code
- Response
- Reason
- Response Type
* - 200
- Data source PROV records
- Successful
- application/json
* - 404
- .. code-block:: json
{
"detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
--------
API Endpoints - Catalogues
--------------------------
Data catalogues are a subset of data sources which contain a number of distinct data sets.
--------
GET /api/datasources/{datasource_id}/datasets/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Implementation notes:
Retrieves the list of dataset IDs within a catalogue, which may be via an API query to the data source, if supported by the data source. The authenticated user must have META permissions or above to access the data source. In the general case, this is implementation-specific for the data connector.
Parameters:
.. list-table::
:widths: 16 80 16
:header-rows: 1
* - Parameter
- Description
- Type
* - datasource_id
- The numeric id of the data source
- integer
Response class (Status 200): application/json
.. code-block:: json
{
"status": "success",
"data": [
"string"
]
Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
* - HTTP Status Code
- Response
- Reason
- Response Type
* - 200
- Data source list of datasets
- Successful
- application/json
* - 400
- .. code-block:: json
{
"status": "error",
"message": "Data source does not contain datasets"
}
- Data source/connector is not a catalogue
- application/json
* - 404
- .. code-block:: json
{
"detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
* - any other
- Error response from external data source
- An error occured within the external data source
- determined by data source
-------- --------
GET /api/datasources/{datasource_id}/datasets/{dataset_id}/metadata/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Implementation notes:
Specific to data sources which purport to act as catalogues of data, it retrieves metadata for a single dataset contained within the given data source in most cases via an API query to the data source (e.g. HyperCat), although is dependent on data connector implementation. The authenticated user must have permission to use the given data source.
Parameters:
.. list-table::
:widths: 16 80 16
:header-rows: 1
* - Parameter
- Description
- Type
* - datasource_id
- The numeric id of the data source
- integer
* - dataset_id
- The id of the data set within the specific data source, which may be a URI
- string
Response class (Status 200): application/json
Dependent on data source
Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
* - HTTP Status Code
- Response
- Reason
- Response Type
* - 200
- Data set metadata
- Successful
- application/json
* - 400
- .. code-block:: json
{
"status": "error",
"message": "Data source does not provide metadata"
}
- Data source/connector does not support metadata queries
- application/json
* - 404
- .. code-block:: json
{
"detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
* - 404
- .. code-block:: json
{
"status": "error",
"message": "Data set does not exist within this data source"
}
- Parameter dataset_id did not refer to a valid dataset within this data source
- application/json
* - any other
- Error response from external data source
- An error occured within the external data source
- determined by data source
--------
GET /api/datasources/{datasource_id}/datasets/{dataset_id}/data/?{query_string}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Implementation notes:
In the case where a data source represents a catalogue of datasets, retrieve a single dataset via an API query to the data source. The authenticated user must have permission to use the given data source.
Parameters:
.. list-table::
:widths: 16 80 16
:header-rows: 1
* - Parameter
- Description
- Type
* - datasource_id
- The numeric id of the data source
- integer
* - dataset_id
- The id of the data set within the specific data source, which may be a URI
- string
* - query_string
- An ampersand-separated set of key=value pairs
- string
Response class (Status 200): type-specific to datasource
Dependent on data source
Responses messages:
.. list-table::
:widths: 16 80 16 16
:header-rows: 1
* - HTTP Status Code
- Response
- Reason
- Response Type
* - 200
- Data set data
- Successful
- application/json
* - 400
- .. code-block:: json
{
"status": "error",
"message": "Data source does not provide data"
}
- Data source/connector does not support data queries
- application/json
* - 404
- .. code-block:: json
{
"detail": "Not found."
}
- Parameter datasource_id was not valid
- application/json
* - 404
- .. code-block:: json
{
"status": "error",
"message": "Data set does not exist within this data source"
}
- Parameter dataset_id did not refer to a valid dataset within this data source
- application/json
* - any other
- Error response from external data source
- An error occured within the external data source
- determined by data source
--------
References References
---------- ----------
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment