GOCDB/Write API/Technical Documentation

From EGIWiki
Jump to: navigation, search

Write API Technical Documentation

Description

The write API currently provides limited functionality to add, update, and delete the extension properties of Sties, Services, and Service Endpoints through the use of a HTTP interface.

Authentication/Authorisation

Authentication is currently via X509 certificate. The expectation is that this is a certificate belonging to the host making the programmatic change.

In order to make changes to any entity, the DN of the certificate being used must be in the list of authorised credentials for the entities parent site. This can be achieved through the web portal by anyone with a role over a site that allows them to modify it. At the bottom of the page showing a site's details is a section titled "Credentials authenticated to use the GOCDB write API" (this will only be visible to those who are able to alter sites). Here new DN's can be added. Caution should be exercised when doing this - certificates with this DN can be used to delete information associated with a site or it's child entities (including child services and endpoints).

Examples use using Curl

An example command using 'PUT' to update extension properties for a site:

 $ curl -i --cacert <path to CA Cert pem> --cert <path to personal cert pem> --key <path to personal cert key pem> -X PUT https://goc.egi.eu/gocdbpi/V5/site/335/ExtensionProperties -d '{"isAwesome":"True","Volume":"11"}'
  • This example will only work if the certificate provided is authorised to alter the site with id 335 (see the section on authentication/authorisation).
  • The '-k' option can be used for testing to disable authentication of the host, but should not be used in a production setting.
  • The '-i' option returns the whole header, allowing the user to see the HTTP response code.
  • The '-d' option allows you to specify the data for the message request body. For the write API, this will always be in JSON format.

An example command using 'DELETE' to remove all the extension properties from a site:

 $ curl -i --cacert <path to CA Cert pem> --cert <path to personal cert pem> --key <path to personal cert key pem> -X DELETE https://goc.egi.eu/gocdbpi/V5/site/335/ExtensionProperties
  • This example will only work if the certificate provided is authorised to alter the site with id 335 (see the section on authentication/authorisation).
  • The '-k' option can be used for testing to disable authentication of the host, but should not be used in a production setting.
  • The '-i' option returns the whole header, allowing the user to see the HTTP response code.
  • Note no data is required for DELETE methods, and so the '-d' option is not used.


An example command using 'put' to update a single extension property for a site:

 $ curl -i --cacert <path to CA Cert pem> --cert <path to personal cert pem> --key <path to personal cert key pem> -X PUT https://goc.egi.eu/gocdbpi/V5/site/335/ExtensionProperties/isAwesome -d '{"value":"True"}'
  • This example will only work if the certificate provided is authorised to alter the site with id 335 (see the section on authentication/authorisation).
  • The '-k' option can be used for testing to disable authentication of the host, but should not be used in a production setting.
  • The '-i' option returns the whole header, allowing the user to see the HTTP response code.
  • The '-d' option allows you to specify the data for the message request body. For the write API, this will always be in JSON format.
  • Note: where the key is provided in the URL, the value should be provided in the format shown.


For full details of supported methods, see the section on supported methods.

Supported methods

The following tables list the methods supported in the write API, and the associated URLs.

Extension Properties

This section covers manipulating extensions properties belonging to various entities with the Write API.

Site

Method URL Request Body Function
POST https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Adds the extension properties defined in the request to the Site with the given ID (fails if extension properties already exist with any of the specified property names)
PUT https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 For the site with the specified ID, adds the specified properties, overwriting any existing ones with the specified names (If none of them are currently defined, the it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Removes all the extension properties specified in the request body for the identified site (fails if any of the listed properties are not currently defined. Note: values do not have to be defined, an empty string can be provided instead. If a value is provided, it must be correct. See Note 3 for examples.
DELETE https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties None or empty Removes all the extension properties for the identified site
POST https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2 Adds an extension property to the identified site with the given name and value in the request (fails if property with that name is already defined)
PUT https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2 Adds an extension property to the identified site, overwriting any exiting property with the given name (If none of that name is already defined, then it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/Site/<Site ID>/ExtensionProperties/<propertyName> None or empty or Value in JSON Format e.g Note 2 Removes the named extension property from the named site (fails if request body is present and the value does not match the current value of the property or if the named property is not defined for the identified Site)

Service

Method URL Request Body Function
POST https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Adds the extension properties defined in the request to the service with the given ID (fails if any of the extension properties are already defined)
PUT https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 For the service with the specified ID, adds the specified properties, overwriting any existing ones with the specified names (If none of them are currently defined, the it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Removes all the extension properties specified in the request body for the identified service (fails if any of the listed properties are not currently defined). Note: values do not have to be defined, an empty string can be provided instead. If a value is provided, it must be correct. See Note 3 for examples.
DELETE https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties None or empty Removes all the extension properties for the identified service
POST https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2 Adds an extension property to the identified service with the given name and value in the request (fails if property with that name is already defined)
PUT https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2 Adds an extension property to the identified service, overwriting any exiting property with the given name (If none of that name is already defined, then it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/ExtensionProperties/<propertyName> None or empty or Value in JSON Format e.g Note 2 Removes the named extension property from the named service (fails if request body is present and the value does not match the current value of the property or if the named property is not defined for the identified Service)

Service Endpoint

Method URL Request Body Function
POST https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Adds the extension properties defined in the request to the SE with the given ID  (fails if any of the extension properties are already defined)
PUT https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 For the SE with the specified ID, adds the specified properties, overwriting any existing ones with the specified names (If none of them are currently defined, the it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties Key value pairs in JSON Format e.g. Note 1 Removes all the extension properties specified in the request body for the identified SE (fails if any of the listed properties are not currently defined). Note: values do not have to be defined, an empty string can be provided instead. If a value is provided, it must be correct. See Note 3 for examples.
DELETE https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties None or empty
Removes all the extension properties for the identified SE
POST https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2
Adds an extension property to the identified SE with the given name and value in the request (fails if property with that name is already defined)
PUT https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties/<propertyName> Value in JSON Format e.g Note 2 Adds an extension property to the identified SE, overwriting any exiting property with the given name (If none of that name is already defined, then it is functionally equivalent to POST)
DELETE https://goc.egi.eu/gocdbpi/v5/EndPoint/<End point ID>/ExtensionProperties/<propertyName> None or empty or Value in JSON Format e.g Note 2 Removes the named extension property from the named SE (fails if request body is present and the value does not match the current value of the property or if the named property is not defined for the identified SE)

Services

As of GOCDB 5.8, updating Service properties via the Write API is allowed.

Method URL Request Body Function
POST https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/<Service Property Name [see Note 4]> Property value in JSON Format e.g. Note 2 For the service with the specified ID, updates the specified property. Fails if the property is already defined. Not a valid method for mandatory or boolean fields.
PUT https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/<Service Property Name [see Note 4]> Property value in JSON Format e.g. Note 2 For the service with the specified ID, updates the specified property, overwriting any existing value with the one specified

Service Endpoints

As of GOCDB 5.8, the Write API allows the following:

  • Creation, updating and deletion of Service Endpoints
  • Updating Service Endpoint properties
Method URL Request Body Function
POST https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/EndPoint End point in JSON format e.g. Note 5 Adds a new end point to the service with the specified ID with the values specified in the request body. If an endpoint with the specified name already exists for the specified service then the operation fails.
PUT https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/EndPoint End point in JSON format e.g. Note 5 Adds a new end point to the service with the specified ID with the values specified in the request body. If an endpoint with the specified name already exists for the specified service then it will be overwritten with new values for each field specified.
DELETE https://goc.egi.eu/gocdbpi/v5/Service/<Service ID>/EndPoint/<End Point ID> None or empty Deletes the specified endpoint. If there is no endpoint with that ID or it doesn't belong to the specified service the operation will fail.
POST https://goc.egi.eu/gocdbpi/v5/EndPoint/<End Point ID>/<End Point Property Name [see Note 6]> Property value in JSON Format e.g. Note 2 For the end point with the specified ID, updates the specified property. Fails if the property is already defined. Not a valid method for mandatory or boolean fields.
PUT https://goc.egi.eu/gocdbpi/v5/EndPoint/<End Point ID>/<End Point Property Name [see Note 6]> Property value in JSON Format e.g. Note 2 For the end point with the specified ID, updates the specified property, overwriting any existing value with the one specified


Note 1: [{"PROPERTY1NAME":"PROPERTY1VALUE","PROPERTY2NAME":"PROPERTY2VALUE","PROPERTY3NAME":"PROPERTY3VALUE"}]

Note 2: [{"value":"PROPERTYVALUE"}]

Note 3: For DELETE methods, the following are functionally equivalent [{"PROPERTY1NAME":"PROPERTY1VALUE","PROPERTY2NAME":"PROPERTY2VALUE","PROPERTY3NAME":"PROPERTY3VALUE"}] and [{"PROPERTY1NAME":"","PROPERTY2NAME":"","PROPERTY3NAME":""}].

Note 4: Properties for service that can be updated are (case-insensitive): Hostname^, Description, Production*, Beta*, Monitored*, Notify*, host_dn, Host_IP, Host_IP_V6, Host_OS, Host_Arch, URL, and Email^. Properties marked with '*' take a boolean value ('true' or 'false' without quotation marks, see [[1]]). Properties marked with '^' are mandatory.

Note 5: [{"name":"ENDPOINTNAME","url":"ENDPOINTURL","interfaceName":"INTERFACENAME","description":"ENDPOINTDESCRIPTION","email":"EMAILADDRESS","monitored":trueORfalse}]. 'name' is mandatory. 'url' is mandatory for POST requests and PUT requsts where there is no existing endpoint with the given name for the given service. If no 'interfacename' is provided then the service type of the parent service will be used by default. If no value is specified for 'monitored' the current 'monitored' value of the parent service will be used by default.

Note 6: Properties for end point that can be updated are (case-insensitive): Name, URL, InterfaceName (if not specified, or blank, defaults to the type of the parent service), Description, Email, and Monitored(boolean value -'true' or 'false' without quotation marks, see [[2]]).