RPC API documentation

How to use Perun RPC

Perun RPC is not using traditional REST API, so please read properly, how are your requests handled and what are expected responses.

Authentication

Authentication of person / component making a request is done by Apache web server and depends on it’s current configuration. Perun can internally handle identity provided by Kerberos, Shibboleth IdP, Certificate or REMOTE_USER like Apache config. Identity info provided by Apache to Perun is used only to match identity to user object from Perun (if exists).

Authorization

Authorization is done on Perun side based on privileges associated with user, which are stored inside Perun. Few methods are accessible without authorization (e.g. in order to allow new users to register to Perun).

Request type GET / POST

We recommend to use POST requests all the time. It’s most simple, since all parameters are transferred in a request body in JSON format and response is the same.

You can optionally use GET requests, but then parameters must be present in a request URL (as a query) and you can call only listing methods (get, list). Methods changing state (create, delete, update, add, remove,…) must be POST.

URL structure

http(s)://[server]/[authentication]/rpc/[format]/[manager]/[method]?[params]
[server]
Is hostname of your Perun instance.
[authentication]
Is type of expected authentication which must be supported by Perun instance. Standard values are: fed (Shibboleth IDP), krb (Kerberos), cert (Certificate), non (without authorization).
[format]
Format of data for transfer. Possible values are: json, jsonp and voot.
[manager]
Name of manager to call method in (in a camel case).
[method]
Name of method to call from selected manager (in a camel case).
[params]
Query parameters passed in URL (for GET requests) in a following manner:
?param1=value&param2=value&listParam[]=value1&listParam[]=value2

Passing parameters

When using GET requests, method parameters must be present in a URL (see above for full overview).

URL:  ...vosManager/getVoById?id=123

When using POST, expected parameters are properties of JSON object in request body, eg.:

URL:  ...vosManager/getVoById
Body: { "id": 123 }

If you are passing whole objects (e.g. on object creation), you usually omit not relevant properties and id is set to 0.

URL:  ...vosManager/createVo
Body: { "id": 0 , "name" : "My VO" , "shortName" : "myVo" }

Note: VO object is missing properties like: beanName, createdAt, createdBy etc.

Perun API is using mostly only IDs of objects, so you don’t have to care about exact object properties values. Objects are retrieved only internally and must pass existence and authorization checks.

HTTP return codes

If OK, all requests to Perun API returns 200 return code.

When processing of your request throws an exception in java code, response is still 200, but it’s body is replaced with serialized Exception object. Any other return code signalize problem with a server (not found, internal error etc.).

Return values

If response of method call is an object or list of them, correct JSON representation is returned.

If response of method call is null or any primitive type (integer, string, boolean), returned value is simple string. So you will get: null and NOT: { "value": null }

Usage of JSON/JSONP formats

Perun can handle both formats. While both consumes valid JSON as input, second one produces response with padding:

Request:  someUrl?callback=call1&param=value
Response: call1(response);

If you omit callback query parameter, you will get:

Response: null(response);

When using JSONP, returned objects are stripped of non relevant properties like createdAt, createdBy, modifiedAt, modifiedBy etc. You can get them when using standard JSON.