Perun RPC is not using traditional REST API, so please read properly, how are your requests handled and what are expected responses.
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 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).
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.
http(s)://[server]/[authentication]/rpc/[format]/[manager]/[method]?[params]?param1=value¶m2=value&listParam[]=value1&listParam[]=value2
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.
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.).
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 }
Perun can handle both formats. While both consumes valid JSON as input, second one produces response with padding:
Request: someUrl?callback=call1¶m=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.
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.