TNA3.4 AppDB REST API v0.2

From EGIWiki
Jump to: navigation, search

Introduction

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 version 0.2.

Conventions used in this document

{} : contains a variable value. The variables are:

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/0.2/{resource}/<{parameter} | {query} >

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/0.2/applications/ 
http://appdb-pi.egi.eu/rest/0.2/applications/50/

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/0.2/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/0.2/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 named “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/0.2/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/0.2/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 it's 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.
tag text an application tag value. For a list of available tags refer to tags
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/rest/0.2/applications/?addedon=2010-04&pagelength=2
  • Fetch all applications which contain the phrase “time evolution” in their description text.
    http://appdb-pi.egi.eu/rest/0.2/applications/?description=time%20evolution

Application entry

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

Related Applications

Url template http://appdb-pi.egi.eu/rest/0.2/applications/{id}/relatedapps
Description Returns a list of application entries whose content is related to the application entry of the given id.
Type list
Response type application
Schema file http://appdb-pi.egi.eu/rest/0.2/schema/application
Parameters
name type description
id number the application's entry id in the applications database.
Examples
  • Get the related applications for the application with id = 172
    http://appdb-pi.egi.eu/rest/0.2/applications/172/relatedapps

Applications Ratings

Url template http://appdb-pi.egi.eu/rest/0.2/applications/{id}/ratings
Description Returns a list of rating entries for the application entry with the given id.
Type list
Response type rating
Schema file http://appdb-pi.egi.eu/rest/0.2/schema/apprating
Parameters
name type description
id number the application's entry id in the applications database.
Examples
  • Get the ratings submitted for the application with id = 172
    http://appdb-pi.egi.eu/rest/0.2/applications/172/ratings

Applications Ratings Report

Url template http://appdb-pi.egi.eu/rest/0.2/applications/{id}/ratingsreport/<{type}>
Description Returns a summary of votes for each rating value (stars) for the application entry with the given id.
Type entry
Response type ratingreport
Schema file http://appdb-pi.egi.eu/rest/0.2/schema/appratingreport
Parameters
name type description
id number the application's entry id in the applications database.
type text The type of submitter. To retrieve the rating summary of authenticated users only set the value of type to internal, for non-authenticated users only set to external and for all types set to both. The default value is both.
Examples
  • Get the report of rating submitted by authenticated users for the application with id = 172
    http://appdb-pi.egi.eu/rest/0.2/applications/172/ratingsreport/internal

People list

Url template http://appdb-pi.egi.eu/rest/0.2/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/0.2/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.
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/rest/0.2/people/?firstname=Sebastian
  • Get all the validated people.
    http://appdb-pi.egi.eu/rest/0.2/people/?rolevalidated=true

Person entry

Url template http://appdb-pi.egi.eu/rest/0.2/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/0.2/schema/person
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/rest/0.2/people/3/

Regional

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

Disciplines

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

Statuses

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

Middlewares

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

Roles

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

Tags

Url template http://appdb-pi.egi.eu/rest/0.2/tags/
Description Returns a list of all registered tags in the applications database with the count of their occurrences.
Type list
Response type tag
Parameters none
Query parameters none

Contact Types

Url template http://appdb-pi.egi.eu/rest/0.2/contacttypes/
Description Returns a list of types of people contacts supported by the applications database system.
Type list
Response type contact
Schema file http://appdb-pi.egi.eu/rest/0.2/schema/person/
Parameters none
Query parameters none

Schema list

Url template http://appdb-pi.egi.eu/rest/0.2/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/0.2/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
  • Get the application schema
    http://appdb-pi.egi.eu/rest/0.2/schema/application/