Alert.png The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.

Difference between revisions of "TNA3.4 AppDB REST API v0.1"

From EGIWiki
Jump to navigation Jump to search
m
(No difference)

Revision as of 19:36, 8 February 2011

Indroduction

This document is intended for developers who want to write applications to interact with the AppDB API using REST. The AppDB web portal is located at http://appdb.egi.eu/ . This API will allow you to retrieve information from your own application 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 error message response. All methods of the API are given in the following format:

http://appdb-pi.egi.eu/{version}/{resource}/<{parameter} | {query} >

The resource types are descripted in API Reference. 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). For example:

http://appdb-pi.egi.eu/{version}/applications/ 
http://appdb-pi.egi.eu/{version}/applications/23/

All methods return XML documents conforming to schema files according to the data you wish to retrieve. Each file describes each entity of the AppDB that can be retrieved using the API. These files are located at:

http://appdb-pi.egi.euapi/schema/{version}/

To get the complete list of all the files , one should do a GET HTTP request to the following url:

http://appdb-pi.egi.eu/{version}/xsd/

The above will return a XML document with a node for each file. Each node has two attributes. The first attribute is the named “name” and denotes the the entity to be retrieved while the second named “uri” which denotes the location of the schema file.

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/{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/schema/{version}/application.xsd
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
  • Fetch all applications added on April of 2010, with two elements on each page:
    http://appdb-pi.egi.eu/0.1/applications/?addedon=2010-04&pagelength=2
  • Fetch all applications which contain the phrase “time evolution” in their description text.
    http://appdb-pi.egi.eu/0.1/applications/?description=time%20evolution

Application entry

Url template http://appdb-pi.egi.eu/{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/schema/{version}/application.xsd
Parameters
name type description
id number the application's entry id in the applications database.
Examples
  • Get the application registered with id = 2
    http://appdb-pi.egi.eu/0.1/applications/2/

Publication list

Url template http://appdb-pi.egi.eu/{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/schema/{version}/publication.xsd
Parameters
name type description
id number the application's entry id in the applications database.
Examples
  • Get the publications of the application registered with id = 2
    http://appdb-pi.egi.eu/0.1/applications/2/publications

Contact list

Url template http://appdb-pi.egi.eu/{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/schema/{version}/person.xsd
Parameters
name type description
id number the application's entry id in the applications database.
Examples
  • Get the contacts of the application registered with id = 2
    http://appdb-pi.egi.eu/0.1/applications/2/contacts

People list

Url template http://appdb-pi.egi.eu/{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/schema/{version}/person.xsd
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
  • Get the people with first name Sebastian:
    http://appdb-pi.egi.eu/0.1/people/?firstname=Sebastian
  • Get all the validated people.
    http://appdb-pi.egi.eu/0.1/people/?rolevalidated=true

Person entry

Url template http://appdb-pi.egi.eu/{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/schema/{version}/person.xsd
Query parameters
name type description
id number the id of a person's entry in the applications database.
Examples
  • Get the person with id=3
    http://appdb-pi.egi.eu/0.1/people/3/

Regional

Url template http://appdb-pi.egi.eu/{version}/regional/
Description Returns a list of all countries and regions.
Type list
Response type country, region
Schema file http://appdb-pi.egi.eu/schema/{version}/regional.xsd
Parameters none
Query parameters none

Disciplines

Url template http://appdb-pi.egi.eu/{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/schema/{version}/application.xsd
Parameters none
Query parameters none

Statuses

Url template http://appdb-pi.egi.eu/{version}/statuses/
Description Returns a list of all status types.
Type list
Response type status
Schema file http://appdb-pi.egi.eu/schema/{version}/application.xsd
Parameters none
Query parameters none

Middlewares

Url template http://appdb-pi.egi.eu/{version}/middlewares/
Description Returns a list of all middleware types.
Type list
Response type middleware
Schema file http://appdb-pi.egi.eu/schema/{version}/application.xsd
Parameters none
Query parameters none

Roles

Url template http://appdb-pi.egi.eu/{version}/roles/
Description Returns a list of all role types.
Type list
Response type role
Schema file http://appdb-pi.egi.eu/schema/{version}/person.xsd
Parameters none
Query parameters none

Xsd list

Url template http://appdb-pi.egi.eu/{version}/xsd/
Description Returns the locations of all xml schemas for the response data types.
Type list
Response type none
Schema file none
Parameters none
Query parameters none