Difference between revisions of "TNA3.4 AppDB REST API v0.1"
(First submission of AppDB API page) |
|||
(9 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
[[Category: Community Engagement]] | |||
=Indroduction= | =Indroduction= | ||
This document is intended for developers who want to write applications | This document is intended for developers who want to write applications that interact with the AppDB API using REST. The API is located at http://appdb-pi.egi.eu and it allows information retrieval from third party applications without having to reside on the rich user interface of the AppDB portal. Thus one is given the opportunity to design one's own front ends. This only document covers the read-only operations of the API for its beta version 0.1. | ||
=Conventions used in this document= | =Conventions used in this document= | ||
{} : contains a variable value. The variables are: | {} : contains a variable value. The variables are: | ||
Line 8: | Line 10: | ||
<>: contains an optional variable or value. | <>: contains an optional variable or value. | ||
= Getting started = | = Getting started = | ||
The read-only API operations are attained only by the use of HTTP GET requests. The use of any other verb like POST,PUT or DELETE will result in an | The read-only API operations are attained only by the use of HTTP GET requests. The use of any other verb like POST,PUT or DELETE will result in an 404 HTTP response. All methods of the API are given in the following format:<br /> | ||
: | :<pre>http://appdb-pi.egi.eu/rest/{version}/{resource}/<{parameter} | {query} ></pre> | ||
The version is composed by the major and the minor number. This is necessary in order to avoid possible incompatibilities between the code of the consumer application and the service application (AppDB). | The version is composed by the major and the minor number. This is necessary in order to avoid possible incompatibilities between the code of the consumer application and the service application (AppDB).The resource name for each request can be found in the [[#API_reference | API Reference]]. Some requests can also take either parameters or queries, as in the example given bellow:<br /> | ||
: | :<pre>http://appdb-pi.egi.eu/rest/{version}/applications/ </pre> | ||
: | :<pre>http://appdb-pi.egi.eu/rest/{version}/applications/23/</pre> | ||
All methods return XML documents conforming to | All methods return XML documents conforming to schemata according to the user request. The user can request a list of these schemata from the following address:<br /> | ||
: | :<pre>http://appdb-pi.egi.eu/rest/{version}/schema/</pre> | ||
The list is composed of elements with two attributes.The "name" attribute refers to the name of the schema and the "uri" attribute points the location of the schema. To get each schema separately, the user should send a GET HTTP request with the schema name given from the list, as shown bellow:<br /> | |||
: | :<pre>http://appdb-pi.egi.eu/rest/{version}/schema/{schemaname}/</pre> | ||
The | The response will be a XSD document describing the corresponding data type. | ||
==Query operations== | ==Query operations== | ||
The API provides query operations for the list and detailed list response types which allow query parameters. The query is provided as a classic url query string. The valid parameters of the query differ from each list data type and are described in the API reference. Parameter naming is case-sensitive and they should be given in lowercase. If an invalid parameter name is given the server will respond with an error “Invalid Query property”. It is also a good practice to escape the parameter values before sending them to the API. | The API provides query operations for the list and detailed list response types which allow query parameters. The query is provided as a classic url query string. The valid parameters of the query differ from each list data type and are described in the API reference. Parameter naming is case-sensitive and they should be given in lowercase. If an invalid parameter name is given the server will respond with an error “Invalid Query property”. It is also a good practice to escape the parameter values before sending them to the API. | ||
Line 36: | Line 38: | ||
*error (string) : If an error occurs this attribute will contain the error message. | *error (string) : If an error occurs this attribute will contain the error message. | ||
There are two more attributes used for displaying paging information, which are described in the paging section of this document. | There are two more attributes used for displaying paging information, which are described in the paging section of this document. | ||
= API reference = | = API reference = | ||
==Application list== | ==Application list== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px;" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/applications/<{query}></nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all the applications registered in applications database. | | '''Description''' || colspan="2" | Returns a list of all the applications registered in applications database. | ||
Line 48: | Line 51: | ||
| '''Response type''' || colspan="2" | application | | '''Response type''' || colspan="2" | application | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/application</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 88: | Line 91: | ||
| colspan="3" align="left" | '''Examples''' | | colspan="3" align="left" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Fetch all applications added on April of 2010, with two elements on each page: <pre>http://appdb-pi.egi.eu/0.1/applications/?addedon=2010-04&pagelength=2</pre></li><li>Fetch all applications which contain the phrase “time evolution” in their description text.<br /><pre>http://appdb-pi.egi.eu/0.1/applications/?description=time%20evolution</pre></li> | | colspan="3" | <ul><li>Fetch all applications added on April of 2010, with two elements on each page: <pre>http://appdb-pi.egi.eu/rest/0.1/applications/?addedon=2010-04&pagelength=2</pre></li><li>Fetch all applications which contain the phrase “time evolution” in their description text.<br /><pre>http://appdb-pi.egi.eu/rest/0.1/applications/?description=time%20evolution</pre></li> | ||
|- | |- | ||
|} | |} | ||
==Application entry== | ==Application entry== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/applications/{id}</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns an application entry registered in applications database with the given id. | | '''Description''' || colspan="2" | Returns an application entry registered in applications database with the given id. | ||
Line 102: | Line 105: | ||
| '''Response type''' || colspan="2" | application | | '''Response type''' || colspan="2" | application | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/application</nowiki> | ||
|- | |- | ||
| colspan="3" align="left" | '''Parameters''' | | colspan="3" align="left" | '''Parameters''' | ||
Line 114: | Line 117: | ||
| colspan="3" | '''Examples''' | | colspan="3" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Get the application registered with id = 2<pre>http://appdb-pi.egi.eu/0.1/applications/2/</pre></li></ul> | | colspan="3" | <ul><li>Get the application registered with id = 2<pre>http://appdb-pi.egi.eu/rest/0.1/applications/2/</pre></li></ul> | ||
|- | |- | ||
|} | |} | ||
==Publication list== | ==Publication list== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/applications/{id}/publications</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns the publication list of an application entry registered in applications database with the given id. | | '''Description''' || colspan="2" | Returns the publication list of an application entry registered in applications database with the given id. | ||
Line 128: | Line 131: | ||
| '''Response type''' || colspan="2" | publication | | '''Response type''' || colspan="2" | publication | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/publication</nowiki> | ||
|- | |- | ||
| colspan="3" align="left" | '''Parameters''' | | colspan="3" align="left" | '''Parameters''' | ||
Line 140: | Line 143: | ||
| colspan="3" | '''Examples''' | | colspan="3" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Get the publications of the application registered with id = 2<pre>http://appdb-pi.egi.eu/0.1/applications/2/publications</pre></li></ul> | | colspan="3" | <ul><li>Get the publications of the application registered with id = 2<pre>http://appdb-pi.egi.eu/rest/0.1/applications/2/publications</pre></li></ul> | ||
|- | |- | ||
|} | |} | ||
==Contact list== | ==Contact list== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/applications/{id}/contacts</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns the contact list of an application entry registered in applications database with the given id. | | '''Description''' || colspan="2" | Returns the contact list of an application entry registered in applications database with the given id. | ||
Line 154: | Line 157: | ||
| '''Response type''' || colspan="2" | person | | '''Response type''' || colspan="2" | person | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/person</nowiki> | ||
|- | |- | ||
| colspan="3" align="left" | '''Parameters''' | | colspan="3" align="left" | '''Parameters''' | ||
Line 166: | Line 169: | ||
| colspan="3" | '''Examples''' | | colspan="3" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Get the contacts of the application registered with id = 2<pre>http://appdb-pi.egi.eu/0.1/applications/2/contacts</pre></li></ul> | | colspan="3" | <ul><li>Get the contacts of the application registered with id = 2<pre>http://appdb-pi.egi.eu/rest/0.1/applications/2/contacts</pre></li></ul> | ||
|- | |- | ||
|} | |} | ||
==People list== | ==People list== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/people/<{query}></nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all people registered in applications database. | | '''Description''' || colspan="2" | Returns a list of all people registered in applications database. | ||
Line 180: | Line 183: | ||
| '''Response type''' || colspan="2" | person | | '''Response type''' || colspan="2" | person | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/person</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 212: | Line 215: | ||
| colspan="3" align="left" | '''Examples''' | | colspan="3" align="left" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Get the people with first name Sebastian: <pre>http://appdb-pi.egi.eu/0.1/people/?firstname=Sebastian</pre></li><li>Get all the validated people.<br /><pre>http://appdb-pi.egi.eu/0.1/people/?rolevalidated=true</pre></li> | | colspan="3" | <ul><li>Get the people with first name Sebastian: <pre>http://appdb-pi.egi.eu/rest/0.1/people/?firstname=Sebastian</pre></li><li>Get all the validated people.<br /><pre>http://appdb-pi.egi.eu/rest/0.1/people/?rolevalidated=true</pre></li> | ||
|- | |- | ||
|} | |} | ||
==Person entry== | ==Person entry== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/people/{id}/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a single person entry from the applications database with the given id. | | '''Description''' || colspan="2" | Returns a single person entry from the applications database with the given id. | ||
Line 226: | Line 229: | ||
| '''Response type''' || colspan="2" | person | | '''Response type''' || colspan="2" | person | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/person</nowiki> | ||
|- | |- | ||
| colspan="3" align="left" | ''' | | colspan="3" align="left" | '''Parameters''' | ||
|- | |- | ||
! scope="col" style="width:100px" | name | ! scope="col" style="width:100px" | name | ||
! scope="col" style="width:10px" | type | ! scope="col" style="width:10px;" | type | ||
! scope="col" | description | ! scope="col" | description | ||
|- | |- | ||
Line 238: | Line 241: | ||
| colspan="3" | '''Examples''' | | colspan="3" | '''Examples''' | ||
|- | |- | ||
| colspan="3" | <ul><li>Get the person with id=3<pre>http://appdb-pi.egi.eu/0.1/people/3/</pre></li></ul> | | colspan="3" | <ul><li>Get the person with id=3<pre>http://appdb-pi.egi.eu/rest/0.1/people/3/</pre></li></ul> | ||
|- | |- | ||
|} | |} | ||
==Regional== | ==Regional== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/regional/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all countries and regions. | | '''Description''' || colspan="2" | Returns a list of all countries and regions. | ||
Line 252: | Line 255: | ||
| '''Response type''' || colspan="2" | country, region | | '''Response type''' || colspan="2" | country, region | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/regional</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 260: | Line 263: | ||
|} | |} | ||
==Disciplines== | ==Disciplines== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/disciplines/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all registered disciplines and sub disciplines. | | '''Description''' || colspan="2" | Returns a list of all registered disciplines and sub disciplines. | ||
Line 270: | Line 273: | ||
| '''Response type''' || colspan="2" | discipline,subdiscipline | | '''Response type''' || colspan="2" | discipline,subdiscipline | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/application</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 278: | Line 281: | ||
|} | |} | ||
==Statuses== | ==Statuses== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/statuses/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all status types. | | '''Description''' || colspan="2" | Returns a list of all status types. | ||
Line 288: | Line 291: | ||
| '''Response type''' || colspan="2" | status | | '''Response type''' || colspan="2" | status | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/application/</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 296: | Line 299: | ||
|} | |} | ||
==Middlewares== | ==Middlewares== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/middlewares/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all middleware types. | | '''Description''' || colspan="2" | Returns a list of all middleware types. | ||
Line 306: | Line 309: | ||
| '''Response type''' || colspan="2" | middleware | | '''Response type''' || colspan="2" | middleware | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/application/</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 314: | Line 317: | ||
|} | |} | ||
==Roles== | ==Roles== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/roles/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns a list of all role types. | | '''Description''' || colspan="2" | Returns a list of all role types. | ||
Line 324: | Line 327: | ||
| '''Response type''' || colspan="2" | role | | '''Response type''' || colspan="2" | role | ||
|- | |- | ||
| '''Schema file''' || colspan="2" | < | | '''Schema file''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/person/</nowiki> | ||
|- | |- | ||
| '''Parameters''' || colspan="2" | none | | '''Parameters''' || colspan="2" | none | ||
Line 331: | Line 334: | ||
|- | |- | ||
|} | |} | ||
== | ==Schema list== | ||
{| class=" | {| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | ||
|- | |- | ||
| width="150px" | '''Url template''' || colspan="2" | < | | width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/</nowiki> | ||
|- | |- | ||
| '''Description''' || colspan="2" | Returns the locations of all xml | | '''Description''' || colspan="2" | Returns a list with the names and the locations of all xml schemata for the response data types. | ||
|- | |- | ||
| '''Type''' || colspan="2" | list | | '''Type''' || colspan="2" | list | ||
Line 347: | Line 350: | ||
|- | |- | ||
| '''Query parameters''' || cospan="2" | none | | '''Query parameters''' || cospan="2" | none | ||
|- | |||
|} | |||
==Schema Entry== | |||
{| class="mw-listgrouprights-table" style="margin-left:10px;margin-top:0px" width="100%" | |||
|- | |||
| width="150px" | '''Url template''' || colspan="2" | <nowiki>http://appdb-pi.egi.eu/rest/{version}/schema/{name}</nowiki> | |||
|- | |||
| '''Description''' || colspan="2" | Returns a list with the names and the locations of all xml schemata for the response data types. | |||
|- | |||
| '''Type''' || colspan="2" | list | |||
|- | |||
| '''Response type''' || colspan="2" | none | |||
|- | |||
| '''Schema file''' || colspan="2" | none | |||
|- | |||
| colspan="3" align="left" | '''Parameters''' | |||
|- | |||
! scope="col" style="width:100px" | name | |||
! scope="col" style="width:10px" | type | |||
! scope="col" | description | |||
|- | |||
| align="right" | '''name''' || <small>text</small> || the schema's name. | |||
|- | |||
| colspan="3" | '''Examples''' | |||
|- | |||
| colspan="3" | <ul><li>Get the application schema<pre>http://appdb-pi.egi.eu/rest/0.1/schema/application/</pre></li></ul> | |||
|- | |- | ||
|} | |} |
Latest revision as of 13:41, 20 December 2012
Indroduction
This document is intended for developers who want to write applications that interact with the AppDB API using REST. The API is located at http://appdb-pi.egi.eu and it allows information retrieval from third party applications without having to reside on the rich user interface of the AppDB portal. Thus one is given the opportunity to design one's own front ends. This only document covers the read-only operations of the API for its beta version 0.1.
Conventions used in this document
{} : contains a variable value. The variables are:
- version: the version number of the API to be used by the client,e.g. 1.0
- query: used by the list requests as a url query string, e.g. ?variable1=value1&variable2=value2
- id : the id of a specific entry.
<>: contains an optional variable or value.
Getting started
The read-only API operations are attained only by the use of HTTP GET requests. The use of any other verb like POST,PUT or DELETE will result in an 404 HTTP response. All methods of the API are given in the following format:
http://appdb-pi.egi.eu/rest/{version}/{resource}/<{parameter} | {query} >
The version is composed by the major and the minor number. This is necessary in order to avoid possible incompatibilities between the code of the consumer application and the service application (AppDB).The resource name for each request can be found in the API Reference. Some requests can also take either parameters or queries, as in the example given bellow:
http://appdb-pi.egi.eu/rest/{version}/applications/
http://appdb-pi.egi.eu/rest/{version}/applications/23/
All methods return XML documents conforming to schemata according to the user request. The user can request a list of these schemata from the following address:
http://appdb-pi.egi.eu/rest/{version}/schema/
The list is composed of elements with two attributes.The "name" attribute refers to the name of the schema and the "uri" attribute points the location of the schema. To get each schema separately, the user should send a GET HTTP request with the schema name given from the list, as shown bellow:
http://appdb-pi.egi.eu/rest/{version}/schema/{schemaname}/
The response will be a XSD document describing the corresponding data type.
Query operations
The API provides query operations for the list and detailed list response types which allow query parameters. The query is provided as a classic url query string. The valid parameters of the query differ from each list data type and are described in the API reference. Parameter naming is case-sensitive and they should be given in lowercase. If an invalid parameter name is given the server will respond with an error “Invalid Query property”. It is also a good practice to escape the parameter values before sending them to the API.
Paging
The paging mechanism that the API provides can be used through two query parameters (if allowed) and can be displayed in the attributes of the root element of the response XML document. The query parameters are these:
- pagelength : defines the count of entries to be displayed in each page.
- pageoffset : defines the position in the list of entries from which the page will start.
So if the client wants a list of 50 entries and wants to display the first 10, then the parameters should be set as page length=10 and page offset=0. To view the next 10 entries it should change the page offset to 10, for the next 10 should set page length to 20 etc. One must remember that paging is not valid for all resources, as documented in the query parameters section in the API reference. A final note about paging is that if the client hasn't enable paging, the server will do so by setting the default maximum value for the page length parameter for the specific response type. If the paging parameters were set by the client but the page length exceeds that of the server's default maximum value, then the later is used. Otherwise the page length set by the client will be used.
Response types
Because the API conforms to the REST architecture style, it treats every request as a resource request. It responds with a representation of the resource as a XML document. These documents are described with schema files which reside publicly in the web server. All the XML documents are enveloped in a common root element called “appdb” with attributes that describe request statuses, such as paging, or error report. These attributes are:
- count (number) : the count of the entries found in the applications database. In case of paging, where only partial results return, the attribute is left unaffected.
- datatype (string) : he type of the data enclosed in the response as defined in the XML schema.
- type (string) : the type of response. Possible values are:
- list: A collection of references to entries in the applications' database. In order to obtain the referenced entry, a request should be made using the entry's id.
- entry: Detailed information about an entry in the applications' database. Paging is never used for this type of response.
- version (number) : The version of the API.
- error (string) : If an error occurs this attribute will contain the error message.
There are two more attributes used for displaying paging information, which are described in the paging section of this document.
API reference
Application list
Url template | http://appdb-pi.egi.eu/rest/{version}/applications/<{query}> | |
Description | Returns a list of all the applications registered in applications database. | |
Type | list | |
Response type | application | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/application | |
Parameters | none | |
Query parameters | ||
name | type | description |
---|---|---|
name | text | the name of an application. The API will also return any application which contains with the given value in its name. |
description | text | the description text of an application. The API will also return any application which contains the given value in its description. |
abstract | text | the abstract text of an application. The API will also return any application which contains the given value in its abstract. |
discipline | number | the discipline id. For a list of disciplines refer to list disciplines |
subdiscipline | number | the sub-discipline id. For a list of sub-disciplines refer to disciplines |
status | number | the status id. For a list of statuses refer to statuses |
region | number | the region id. For a list of regions refer to regional |
country | number | the country id. For a list of countries refer to regional |
middleware | number | the middleware id.For a list of middlewares refer to middlewares |
addedon | text | the date which the application was added in the applications database. The formatting of the date is YYYY-MM-DD HH:mm:ss. Because its a type of string the client can provide a partial date string and get the corresponding results without an error. |
vo | number | the virtual organization id that the application cooperates with. |
tool | boolean | indicates that the application is a tool. The valid values are 'true' or 'false'.The client can also set the values as '0' for false and any positive value as true. |
pagelength | number | the length of the application list. It must be a positive integer. |
pageoffset | number | the current index of the application list. It must be a positive integer. |
Examples | ||
|
Application entry
Url template | http://appdb-pi.egi.eu/rest/{version}/applications/{id} | |
Description | Returns an application entry registered in applications database with the given id. | |
Type | entry | |
Response type | application | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/application | |
Parameters | ||
name | type | description |
---|---|---|
id | number | the application's entry id in the applications database. |
Examples | ||
|
Publication list
Url template | http://appdb-pi.egi.eu/rest/{version}/applications/{id}/publications | |
Description | Returns the publication list of an application entry registered in applications database with the given id. | |
Type | list | |
Response type | publication | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/publication | |
Parameters | ||
name | type | description |
---|---|---|
id | number | the application's entry id in the applications database. |
Examples | ||
|
Contact list
Url template | http://appdb-pi.egi.eu/rest/{version}/applications/{id}/contacts | |
Description | Returns the contact list of an application entry registered in applications database with the given id. | |
Type | list | |
Response type | person | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/person | |
Parameters | ||
name | type | description |
---|---|---|
id | number | the application's entry id in the applications database. |
Examples | ||
|
People list
Url template | http://appdb-pi.egi.eu/rest/{version}/people/<{query}> | |
Description | Returns a list of all people registered in applications database. | |
Type | list | |
Response type | person | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/person | |
Parameters | none | |
Query parameters | ||
name | type | description |
---|---|---|
firstname | text | the first name of a person. The API will also return any person whose first name contains the given value. |
lastname | text | the last name of a person. The API will also return any person whose last name contains the given value. |
registeredon | text | the registration date of a person in the applications database. The date format is YYYY-MM-DD HH:mm:ss. Because it is a string type the client can send a partial date string and get the corresponding results without an error. |
institute | text | a person's institute. |
country | number | a person's residence. For a list of countries refer to regional |
role | number | a person's role in application database.For a list of roles refer to roles. |
rolevalidated | boolean | indicates whether a person is validated for a specific role in the applications database. |
documents | number | the number of published documents of a person. |
pagelength | number | the length of the people list. It must be a positive integer. |
pageoffset | number | the current index of the people list. It must be a positive integer. |
Examples | ||
|
Person entry
Url template | http://appdb-pi.egi.eu/rest/{version}/people/{id}/ | |
Description | Returns a single person entry from the applications database with the given id. | |
Type | entry | |
Response type | person | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/person | |
Parameters | ||
name | type | description |
---|---|---|
id | number | the id of a person's entry in the applications database. |
Examples | ||
|
Regional
Url template | http://appdb-pi.egi.eu/rest/{version}/regional/ | |
Description | Returns a list of all countries and regions. | |
Type | list | |
Response type | country, region | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/regional | |
Parameters | none | |
Query parameters | none |
Disciplines
Url template | http://appdb-pi.egi.eu/rest/{version}/disciplines/ | |
Description | Returns a list of all registered disciplines and sub disciplines. | |
Type | list | |
Response type | discipline,subdiscipline | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/application | |
Parameters | none | |
Query parameters | none |
Statuses
Url template | http://appdb-pi.egi.eu/rest/{version}/statuses/ | |
Description | Returns a list of all status types. | |
Type | list | |
Response type | status | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/application/ | |
Parameters | none | |
Query parameters | none |
Middlewares
Url template | http://appdb-pi.egi.eu/rest/{version}/middlewares/ | |
Description | Returns a list of all middleware types. | |
Type | list | |
Response type | middleware | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/application/ | |
Parameters | none | |
Query parameters | none |
Roles
Url template | http://appdb-pi.egi.eu/rest/{version}/roles/ | |
Description | Returns a list of all role types. | |
Type | list | |
Response type | role | |
Schema file | http://appdb-pi.egi.eu/rest/{version}/schema/person/ | |
Parameters | none | |
Query parameters | none |
Schema list
Url template | http://appdb-pi.egi.eu/rest/{version}/schema/ | |
Description | Returns a list with the names and the locations of all xml schemata for the response data types. | |
Type | list | |
Response type | none | |
Schema file | none | |
Parameters | none | |
Query parameters | none |
Schema Entry
Url template | http://appdb-pi.egi.eu/rest/{version}/schema/{name} | |
Description | Returns a list with the names and the locations of all xml schemata for the response data types. | |
Type | list | |
Response type | none | |
Schema file | none | |
Parameters | ||
name | type | description |
---|---|---|
name | text | the schema's name. |
Examples | ||
|