Difference between revisions of "GCat Service"
Luca.frosini (Talk | contribs) (→HTTP Statuses) |
Luca.frosini (Talk | contribs) (→Request) |
||
Line 20: | Line 20: | ||
* '''class''' : ''DataCatalogue'' | * '''class''' : ''DataCatalogue'' | ||
* '''name''' : ''science-catalogue'' | * '''name''' : ''science-catalogue'' | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== HTTP Headers === | === HTTP Headers === | ||
Line 106: | Line 66: | ||
A complete list of HTTP Status can be found here: | A complete list of HTTP Status can be found here: | ||
[https://httpstatuses.com/ https://httpstatuses.com/] | [https://httpstatuses.com/ https://httpstatuses.com/] | ||
+ | |||
+ | |||
+ | === 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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! Operation || HTTP Method || URL || Success Code | ||
+ | |- | ||
+ | | List || GET || /{COLLECTION} || 200 OK | ||
+ | |- | ||
+ | | Create || POST || /{COLLECTION} || 201 Created | ||
+ | |- | ||
+ | | Read || GET || /{COLLECTION}/{INSTANCE_ID} || 200 OK | ||
+ | |- | ||
+ | | Update || PUT || /{COLLECTION}/{INSTANCE_ID} || 200 OK | ||
+ | |- | ||
+ | | Patch || PATCH || /{COLLECTION}/{INSTANCE_ID} || 200 OK | ||
+ | |- | ||
+ | | Delete || DELETE || /{COLLECTION}/{INSTANCE_ID} || 200 OK | ||
+ | |- | ||
+ | | Purge || PURGE || /{COLLECTION}/{INSTANCE_ID} || 200 OK | ||
+ | |- | ||
+ | | Purge || DELETE || /{COLLECTION}/{INSTANCE_ID}?purge=true || 200 OK | ||
+ | |} | ||
+ | |||
+ | |||
+ | 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/ 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. [https://varnish-cache.org/docs/3.0/tutorial/purging.html Varnish], [https://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F Squid]) | ||
+ | |||
+ | |||
+ | The Science Catalogue provide support for this method but to support a wider range of clients it also provides the Purge action via DELETE with the additional get parameter <pre>purge=true</pre> | ||
== Collections == | == Collections == |
Revision as of 17:51, 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 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 a 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.
Content Type
Any request must contain the indication of the interested content type.
For any operation returning a result, the client must specify the Accept HTTP Header.
Accept: application/json
For any operation sending content to the service, it is necessary to specify the Content-Type HTTP Header.
Content-Type: application/json
Actually, the service accepts and returns only JSON objects.
Except for a profile which can be also requested in XML.
HTTP Statuses
Any successful operation returns 200 OK status code except for create operation which return 201 Created.
A complete list of HTTP Status can be found here: https://httpstatuses.com/
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 | Success Code |
---|---|---|---|
List | GET | /{COLLECTION} | 200 OK |
Create | POST | /{COLLECTION} | 201 Created |
Read | GET | /{COLLECTION}/{INSTANCE_ID} | 200 OK |
Update | PUT | /{COLLECTION}/{INSTANCE_ID} | 200 OK |
Patch | PATCH | /{COLLECTION}/{INSTANCE_ID} | 200 OK |
Delete | DELETE | /{COLLECTION}/{INSTANCE_ID} | 200 OK |
Purge | PURGE | /{COLLECTION}/{INSTANCE_ID} | 200 OK |
Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 200 OK |
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
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 |