Difference between revisions of "EGI AppDB REST API v1.0"
Line 220: | Line 220: | ||
*Authenticated Operations: GET | *Authenticated Operations: GET | ||
List of previous states of an application entry | List of previous states of an application entry.<br/> | ||
Administrative access only. | Administrative access only. | ||
Line 232: | Line 232: | ||
*Authenticated Operations: GET | *Authenticated Operations: GET | ||
Detailed description of a previous state of an application entry | Detailed description of a previous state of an application entry.<br/> | ||
Administrative access only. | Administrative access only. | ||
Line 489: | Line 489: | ||
== Dissemination Log List == | == Dissemination Log List == | ||
*Resource: dissemination/ | |||
*Type: list | |||
*Datatype: dissemination | |||
*Schema: dissemination | |||
*Filtering: no | |||
*Public Operations: none | |||
*Authenticated Operations: GET | |||
List of dissemination messages that have been dispatched to registered users.<br/> | |||
Administrative access only. | |||
== Dissemination Log Entry == | == Dissemination Log Entry == | ||
*Resource: dissemination/{id} | |||
*Type: entry | |||
*Datatype: dissemination | |||
*Schema: dissemination | |||
*Filtering: no | |||
*Public Operations: none | |||
*Authenticated Operations: GET | |||
Detailed description of a dissemination message that has been dispatched to registered users.<br/> | |||
Administrative access only. |
Revision as of 17:09, 13 June 2012
Introduction
This document is intended for developers who want to write applications that interact with the AppDB API over the web using HTTP commands following the REST paradigm. The API is located at http://appdb-pi.egi.eu and it allows information retrieval and modification 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.
Getting started
Operations
Starting with version 1.0, the AppDB API features write access as well, by supporting HTTP verbs such as PUT, POST, and DELETE. Verb mappings to data operations follow a CRUD convention, as depicted in the following table:
Operation |
HTTP Verb |
Create | PUT |
Read | GET |
Update | POST |
Delete | DELETE |
The API also supports the Listing operation (CRUDL extension), by passing the parameter listmode=listing in the querystring when performing a GET request. Please note that in order to simplify the access model, Update operations are always partial, meaning that properties of the resource that is being updated which are entirely missing from the representation, are ignored (i.e. their state in the backend does not change). Therefore, in order to unset/remove a property, one has to explicitly specify it as NULL, provided that this is permitted. This is the reason why Create and Update CRUD mappings are inverted with regards to what is usually accustomed. Finally, the API also supports the OPTIONS HTTP verb, which returns a list of the operations that are permitted, in principle, for the resource in question.
The base URI for this version of the RESTful API is
http://appdb-pi.egi.eu/rest/1.0/
and requests must be followed by at least one resource name, which may be followed by one or more optional sub-resource names, separated by slashes, as in the examples given bellow:
http://appdb-pi.egi.eu/rest/1.0/applications/
http://appdb-pi.egi.eu/rest/1.0/applications/50/
Response types
Because the API conforms to the REST paradigm, responses to all CRUD operations are always XML document representations of the resource in question. These documents are described by 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 status, such as paging, or errors. These attributes are:
- count (number) : the count of the entries found in the applications database. In case of paging, where only a subset of the results gets returned, the attribute is left unaffected.
- pagelength, pageoffset (numbers) : paging data in case the response is a list of resources. More information follows in the next section.
- datatype (string) : an identifier for the resource data that is enclosed in the response as defined in the XML schema.
- type (string) : the type of the 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 that was accessed.
- error (string) : If an error occurs, this attribute will contain the error message.
- host, apihost (strings) : the URIs of the host that provided the data and API access, respectively.
Paging and Filtering
The paging mechanism that the API provides, as far as Read/Listing operations are concerned, 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:
- 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, it 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 explicitly enable paging, then the server will default to a preset paging value, in order to reduce load; this value can be retrieved from the relevant attributes of the response’s root node. 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.
Moreover, some of the API’s resources support filtering when doing Read/Listing operations; filter expressions may be passed in the querystring by assigning a value to the flt parameter, in order to retrieve just the subset of data that match certain criteria. These filter expressions are strings that may range from simple keywords to complex queries. For more information on the syntax, please refer to FAQ item #13 at the AppDB portal.
API Reference
Application List
- Resource: applications/
- Type: list
- Datatype: application
- Schema: application
- Filtering: yes
- Public Operations: GET
- Authenticated Operations: PUT POST
List of all application entries registered in the database
Application Entry
- Resource: applications/{id}
- Type: entry
- Datatype: application
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: DELETE
Detailed description of a specific application entry
Moderated Application List
- Resource: applications/moderated
- Type: list
- Datatype: application
- Schema: application
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET PUT
List of applications that have been moderated some some particular reason, and thus hidden from public view until the issue gets resolved.
Administrative access only.
Application Publication List
- Resource: applications/{id}/publications
- Type: list
- Datatype: publication
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: PUT POST
List of scientific publications related to an application entry.
Application Publication Entry
- Resource: applications/{id}/publications/{id}
- Type: entry
- Datatype: publication
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: DELETE
Detailed description of a publication related to an application entry
Application Tag List
- Resource: applications/{id}/tags
- Type: list
- Datatype: tag
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: PUT
List of tags applied to an application entry
Application Tag Entry
- Resource: applications/{id}/tags/{id}
- Type: entry
- Datatype: tag
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: DELETE
Detailed description of a tag applied to an application
Related Application List
- Resource: applications/{id}/relatedapps
- Type: list
- Datatype: relatedapp
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of applications related to an application entry
Application Rating Report
- Resource: applications/{id}/ratingsreport
- Type: entry
- Datatype: ratingreport
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Report on all user ratings of an application entry
External Application Rating Report
- Resource: applications/{id}/ratingsreport/internal
- Type: entry
- Datatype: ratingreport
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Report on user ratings of an application entry made by registered users
Internal Application Rating Report
- Resource: applications/{id}/ratingsreport/external
- Type: entry
- Datatype: ratingreport
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Report on user ratings of an application entry made by anonymous users
Application Rating List
- Resource: applications/{id}/ratings
- Type: list
- Datatype: rating
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of user rating entries applied to an application entry
Application Rating Entry
- Resource: applications/{id}/ratings/{id}
- Type: entry
- Datatype: rating
- Schema: application
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Detailed description of a rating entry applied to an application entry
Application State History List
- Resource: applications/{id}/history
- Type: list
- Datatype: apphistory
- Schema: history
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
List of previous states of an application entry.
Administrative access only.
Application State History Entry
- Resource: applications/{id}/history/{id}
- Type: entry
- Datatype: apphistory
- Schema: history
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
Detailed description of a previous state of an application entry.
Administrative access only.
Bookmarked Application List
- Resource: people/{id}/applications/bookmarked
- Type: list
- Datatype: application
- Schema: application
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET PUT
List of application entries bookmarked by a user
Bookmarked Application Entry
- Resource: people/{id}/applications/bookmarked/{id}
- Type: entry
- Datatype: application
- Schema: application
- Filtering: N/A
- Public Operations: none
- Authenticated Operations: GET DELETE
Detailed description of an application entry bookmarked by a user
Editable Application List
- Resource: people/{id}/applications/editable
- Type: list
- Datatype: application
- Schema: application
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
List of application entries that a user has permission to edit
Owned Application List
- Resource: people/{id}/applications/owned
- Type: list
- Datatype: application
- Schema: application
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
List of application entries that a user holds ownership of
Associated Application List
- Resource: people/{id}/applications/associated
- Type: list
- Datatype: application
- Schema: application
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
List of application entries that a user is associated to, as a member of the application's contact list
People List
- Resource: people/
- Type: list
- Datatype: person
- Schema: person
- Filtering: yes
- Public Operations: GET
- Authenticated Operations: PUT POST
List of users (people) that have registered with the database
Person Entry
- Resource: people/{id}
- Type: entry
- Datatype: person
- Schema: person
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Detailed description of a user entry
Regional Information List
- Resource: regional/
- Type: list
- Datatype: regional
- Schema: regional
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of countries, regions, and service providers participating in the EGI project and available to application and user entries
Application Category List
- Resource: categories/
- Type: list
- Datatype: category
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of category types available for application entries
Discipline/Subdiscipline List
- Resource: disciplines/
- Type: list
- Datatype: discipline
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of discipline and subdiscipline types available for application entries
Middleware List
- Resource: middlewares/
- Type: list
- Datatype: middleware
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of grid middlewares supported by application entries and VOs
Application Status List
- Resource: statuses/
- Type: list
- Datatype: status
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of status states available to application entries
VO List
- Resource: vos/
- Type: list
- Datatype: vo
- Schema: vo
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of VOs registered with the EGI Operations Portal and available to application entries
VO Entry
- Resource: vos/{id}
- Type: entry
- Datatype: vo
- Schema: vo
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
Detailed description of a VO registered with the EGI Operations Portal and available to application entries
User Role List
- Resource: roles/
- Type: list
- Datatype: role
- Schema: person
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of user roles available, which define base user privileges
Available Tag List
- Resource: tags/
- Type: list
- Datatype: tag
- Schema: application
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of all tag entries that have been attached at least once on any application entry
Contact Type List
- Resource: contacttypes/
- Type: list
- Datatype: tag
- Schema: person
- Filtering: no
- Public Operations: GET
- Authenticated Operations: none
List of contact types available to user contact information entries
Application Filter Normalization
- Resource: applications/filter/normalize
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Validates and normalizes a filter expression for application searches, defined by the querystring parameter flt
Application Filter Reflection
- Resource: applications/filter/reflect
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Returns a nested representation of the filtering expression specifiers available to application searches
Person Filter Normalization
- Resource: people/filter/normalize
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Validates and normalizes a filter expression for user searches, defined by the querystring parameter flt
Person Filter Reflection
- Resource: people/filter/reflect
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Returns a nested representation of the filtering expression specifiers available to user searches
VO Filter Normalization
- Resource: vos/filter/normalize
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Validates and normalizes a filter expression for VO searches, defined by the querystring parameter flt
VO Filter Reflection
- Resource: vos/filter/reflect
- Type: entry
- Datatype: filter
- Schema: filter
- Filtering: N/A
- Public Operations: GET
- Authenticated Operations: none
Returns a nested representation of the filtering expression specifiers available to VO searches
Dissemination Log List
- Resource: dissemination/
- Type: list
- Datatype: dissemination
- Schema: dissemination
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
List of dissemination messages that have been dispatched to registered users.
Administrative access only.
Dissemination Log Entry
- Resource: dissemination/{id}
- Type: entry
- Datatype: dissemination
- Schema: dissemination
- Filtering: no
- Public Operations: none
- Authenticated Operations: GET
Detailed description of a dissemination message that has been dispatched to registered users.
Administrative access only.