Difference between revisions of "GCat Service"
Luca.frosini (Talk | contribs) (→HTTP Methods) |
Luca.frosini (Talk | contribs) (→HTTP Methods) |
||
| Line 54: | Line 54: | ||
You can find more information about this at [https://restfulapi.net/http-methods/ https://restfulapi.net/http-methods/] | 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 it also provides the Purge action via DELETE with the additional get parameter <pres>purge=true</pre>. | ||
=== HTTP Headers === | === HTTP Headers === | ||
Revision as of 18:36, 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)
The Science Catalogue provide support for this method but it also provides the Purge action via DELETE with the additional get parameter <pres>purge=true</pre>.
HTTP Headers
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 |
