Difference between revisions of "GCat Service"
Luca.frosini (Talk | contribs) (→HTTP Methods) |
Luca.frosini (Talk | contribs) (→HTTP Headers) |
||
Line 63: | Line 63: | ||
=== HTTP Headers === | === HTTP Headers === | ||
+ | ==== gCube Authorization Token ==== | ||
+ | |||
+ | Any request performed to Science Catalogue MUST contains the gCube Authorization Token. | ||
+ | |||
+ | This is done using the HTTP Header ''gcube-token'' | ||
+ | |||
+ | <pre>gcube-token: YOUR-TOKEN</pre> | ||
+ | |||
+ | ===== Retrieve your gCube Authorization Token ===== | ||
+ | |||
+ | the gCube Authorization Token is an UUID bound to yourself and a given Infrastructure context. To retrieve it, you just need to go to a VRE for which you are interested and use the Authorisation Options portlet (see below) | ||
+ | |||
+ | [[File:Authorisation_option.png]] | ||
+ | |||
+ | Click on '''Show''' button and select the token. | ||
=== HTTP Statuses === | === HTTP Statuses === |
Revision as of 17:40, 29 November 2018
The gCube Science Catalogue Service is a RESTful web service based on the principles defined in gCube Catalogue
Contents
Request
URL
The URL used to interact with the Science Catalogue Service is composed of two parts:
- Base Service URL (e.g. https:/catalogue.d4science.org/science-catalogue)
- Specific API (e.g. /organizations)
D4Science infrastructure uses cloud facilities allowing to replicate a service to achieve failover and load balancing.
Science Catalogue Service instances can be deployed and undeployed dynamically. For such a reason the Base Service URL MUST NOT be hard-cabled in the code because it can change over time.
To dynamically discover the Base Service URL please use the information system.
You need to discover gCore Resource having:
- class : DataCatalogue
- name : science-catalogue
HTTP Methods
To be RESTful compliant Science Catalogue uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.
The URL pattern is
Operation | HTTP Method | URL |
---|---|---|
List | GET | /{COLLECTION} |
Create | POST | /{COLLECTION} |
Read | GET | /{COLLECTION}/{INSTANCE_ID} |
Update | PUT | /{COLLECTION}/{INSTANCE_ID} |
Patch | PATCH | /{COLLECTION}/{INSTANCE_ID} |
Delete | DELETE | /{COLLECTION}/{INSTANCE_ID} |
Purge | PURGE | /{COLLECTION}/{INSTANCE_ID} |
Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true |
Where:
- {COLLECTION} is the plural name of the entity type
- {INSTANCE_ID} is an identification which enables to univocally identify the instance in the collection
You can find more information about this at https://restfulapi.net/http-methods/
PURGE Method is not a standard HTTP Method but is a widely used in service which requires this action (e.g. Varnish, Squid)
purge=true
HTTP Headers
gCube Authorization Token
Any request performed to Science Catalogue MUST contains the gCube Authorization Token.
This is done using the HTTP Header gcube-token
gcube-token: YOUR-TOKEN
Retrieve your gCube Authorization Token
the gCube Authorization Token is an UUID bound to yourself and a given Infrastructure context. To retrieve it, you just need to go to a VRE for which you are interested and use the Authorisation Options portlet (see below)
Click on Show button and select the token.
HTTP Statuses
Collections
Group Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /groups |
Create | POST | /groups |
Read | GET | /groups/{NAME} |
Update | PUT | /groups/{NAME} |
Patch | PATCH | /groups/{NAME} |
Delete | DELETE | /groups/{NAME} |
Purge | PURGE | /groups/{NAME} |
Purge | DELETE | /groups/{NAME}?purge=true |
Item Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /items |
Create | POST | /items |
Read | GET | /items/{NAME} |
Update | PUT | /items/{NAME} |
Delete | DELETE | /items/{NAME} |
Purge | PURGE | /items/{NAME} |
Purge | DELETE | /items/{NAME}?purge=true |
Resource Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /items/{NAME}/resources |
Create | POST | /items/{NAME}/resources |
Read | GET | /items/{NAME}/resources/{ID} |
Update | PUT | /items/{NAME}/resources/{ID} |
Delete | DELETE | /items/{NAME}/resources/{ID} |
License Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /licenses |
Organization Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /organizations |
Create | POST | /organizations |
Read | GET | /organizations/{NAME} |
Update | PUT | /organizations/{NAME} |
Patch | PATCH | /organizations/{NAME} |
Delete | DELETE | /organizations/{NAME} |
Purge | PURGE | /organizations/{NAME} |
Purge | DELETE | /organizations/{NAME}?purge=true |
User Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /users |
Create | POST | /users |
Read | GET | /users/{NAME} |
Update | PUT | /users/{NAME} |
Delete | DELETE | /users/{NAME} |
Profile Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /profiles |
Read | GET | /profiles/{NAME} |
A profile is defined using XML. It is possible to get the original XML definition using 'Accept' HTTP Header.
Accept : application/xml
instead of
Accept : application/json
Namespace Collection
Operation | HTTP Method | URL |
---|---|---|
List | GET | /namespaces |