RPC API documentation v17.0.0

Back to Documentation Version:  General How to use Perun RPC Managers AttributesManagerAuditMessagesManagerAuthzResolverCabinetManagerConfigManagerConsentsManagerDatabaseManagerExtSourcesManagerFacilitiesManagerGroupsManagerIntegrationManagerMembersManagerNotificationManagerOwnersManagerRTMessagesManagerRegistrarManagerResourcesManagerSearcherSecurityTeamsManagerServicesManagerTasksManagerUsersManagerVosManager

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. It also supports OIDC authentication using device codeflow. 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), oauth (OIDC), non (without authorization).
[format]
Format of data for transfer. Possible values are: json and jsonp.
[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.

CSRF Protection

Domains with both GUI and API deployed are protected against CSRF attacks as a whole. Even only-API clients must implement this protection or use different domain reserved for the API calls (example below). Perun will generate a CSRF token during the first API call. The token value is returned to the client in a cookie.The client must read the value from the cookie and return it to the API with each call in the appropriate HTTP header along with the cookie itself. As a result, the token value must be the same in the cookie, HTTP header and server-side session. CSRF protection is enabled only for state-changing requests (POST, PUT). Also, CSRF is not used in OIDC, since it has its own CSRF protection using own access tokens.

GUI: perun.<domain>.cz
API: perun-api.<domain>.cz

Presence of CSRF token is checked at first by looking at value of Cookie ('XSRF-TOKEN') and HTTP Session. If either of them is missing, new token is generated and stored into both original Session and Cookie that is stored in the response. Token value must be same for all Cookie, Header ('X-XSRF-TOKEN') and server side Session, in case it is not, corresponding error message is sent in response.