Skip to content

External API

Jump to bottom
Okke Harsta edited this page Sep 4, 2020 · 21 revisions

Create Collaboration

The POST endpoint /api/collaborations/v1 can be used to create a new Collaboration. Use the API Key for the organisation to authenticate:

Authorization: Bearer ${API_KEY}
{
    "name": "new_collaboration",
    "description": "a description of the new CO",
    "administrators": ["[email protected]", "[email protected]"],
    "short_name": "new_short_name",
    "accepted_user_policy": "https://example.edu/aup.txt"
}

The admin of the Collaboration is one of the admins of the Organisation. The response:

{
    "accepted_user_policy": null,
    "access_type": null,
    "created_at": 1560842558.0,
    "created_by": "ext_api",
    "description": null,
    "enrollment": null,
    "global_urn": "uuc:new_short_name",
    "id": 4447,
    "identifier": "8d43c1e8-b3da-4466-a343-e39bbd5f4e13",
    "name": "new_collaboration",
    "organisation_id": 4441,
    "short_name": "new_short_name",
    "status": null,
    "updated_by": "ext_api"
}

Example

─▶ curl -i -H "Content-Type: application/json" -X POST -d '{"name": "Een CO aangemaakt via de api", "administrators": ["[email protected]"], "short_name": "api_test" }' -H "Authorization: Bearer token_copied_from_Org_page" https://sbs.<servername>/api/collaborations/v1
HTTP/1.1 201 CREATED
Date: Fri, 09 Aug 2019 07:15:43 GMT
Server: Apache/2.4.25 (Debian)
Content-Length: 347
x-session-alive: true
Set-Cookie: session=; Expires=Thu, 01-Jan-1970 00:00:00 GMT; Max-Age=0; Path=/
Content-Security-Policy: default-src 'self'; script-src 'self'; frame-ancestors 'none'; form-action 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;
X-Frame-Options: DENY
Referrer-Policy: same-origin
X-Content-Type-Options: nosniff
Content-Type: application/json
Strict-Transport-Security: max-age=16000000; includeSubDomains; preload;

{"accepted_user_policy":null,"access_type":null,"created_at":1565334943.0,"created_by":"ext_api","description":null,"enrollment":null,"global_urn":"org_name:api_test","id":17,"identifier":"4fbd3caa-56de-54e4-bc42-85d34c0ab18b","name":"Een CO aangemaakt via de api","organisation_id":42,"short_name":"api_test","status":"active","updated_by":"ext_api"}

Connect Service to Collaboration

The POST endpoint api/collaborations_services/v1/connect_collaboration_service can be used to connect an existing Service to an existing Collaboration. Use the API Key for the organisation to authenticate:

curl -i -H "Content-Type: application/json" -H "Authorization: Bearer ${API_KEY}" -X PUT -d '{"collaboration_id":2076, "service_entity_id":"https://cloud"}' "http://localhost:8080/api/collaborations_services/v1/connect_collaboration_service"
HTTP/1.0 201 CREATED

{
"collaboration_id":2076,
"collaboration_name":"AI computing",
"collaboration_urn":"ai_computing",
"organisation_name":"UUC",
"service_entity_id":
"https://cloud",
"service_id":4825,
"service_name":"Cloud",
"status":"connected"
}

Create Service Restricted Collaboration

The POST endpoint /api/collaborations/v1/restricted can be used to create a new Collaboration which Services are restricted. Authorise with an out-of-band received API user / password:

Authorization: Basic base64-encoded(user:password)
{
    "name": "new_collaboration",
    "description": "a description of the new CO",
    "administrator": "unix username of an user",
    "short_name": "new_short_name",
    "accepted_user_policy": "https://example.edu/aup.txt",
    "connected_services": ["https://cloud", "https://storage", "https://not_whitelisted"]
}

The schac_home_organisation of the administrator determines the organisation of the Collaboration; if no schac_home_organisation is found, SBS falls back to the default Organization for restricted COs as defined in config.yml.

The response:

{
	"created_at": 1580738647.0,
	"created_by": "sysread",
	"global_urn": "uuc:short_org_name",
	"identifier": "450e2ddb-05d2-407b-b8a1-27aae60d60a2",
	"name": "new_collaboration",
	"organisation_id": 10104,
	"services": [{
		"description": "SARA Cloud Service",
		"entity_id": "https://cloud",
		"name": "Cloud"
	}, {
		"description": "SURF Storage Service",
		"entity_id": "https://storage",
		"name": "Storage"
	}],
	"services_restricted": true,
	"short_name": "short_org_name",
	"status": "active",
	"updated_by": "sysread"
}

Only whitelisted services are actually linked to the new collaboration.

Example

─▶curl -i -u sysread:secret  -H "Content-Type: application/json" -X POST -d \
> '{"name": "new_collaboration", "administrator": "harry", "short_name": "short_org_name", "connected_services": ["https://network","https://wiki","https://storage","https://cloud"]}' \
>  "http://localhost:8080/api/collaborations/v1/restricted" 
HTTP/1.0 201 CREATED
Content-Type: application/json
Content-Length: 1155
x-session-alive: true
server: 
Date: Mon, 03 Feb 2020 15:43:23 GMT
{
	"accepted_user_policy": null,
	"access_type": null,
	"created_at": 1580744603.0,
	"created_by": "sysread",
	"description": null,
	"disable_join_requests": false,
	"enrollment": null,
	"global_urn": "uuc:short_org_name",
	"id": 17595,
	"identifier": "db9bba86-46d5-4732-b4b9-cacd2c6c71ba",
	"name": "new_collaboration",
	"organisation_id": 11701,
	"services": [{
		"accepted_user_policy": null,
		"address": null,
		"automatic_connection_allowed": true,
		"contact_email": null,
		"created_at": 1580742449.0,
		"created_by": "urn:admin",
		"description": "SARA Cloud Service",
		"entity_id": "https://cloud",
		"id": 40725,
		"identity_type": null,
		"name": "Cloud",
		"public_visible": true,
		"status": null,
		"updated_by": "urn:admin",
		"uri": null,
		"white_listed": false
	}, {
		"accepted_user_policy": null,
		"address": null,
		"automatic_connection_allowed": true,
		"contact_email": "[email protected]",
		"created_at": 1580742449.0,
		"created_by": "urn:admin",
		"description": "SURF Storage Service",
		"entity_id": "https://storage",
		"id": 40726,
		"identity_type": null,
		"name": "Storage",
		"public_visible": true,
		"status": null,
		"updated_by": "urn:admin",
		"uri": null,
		"white_listed": true
	}],
	"services_restricted": true,
	"short_name": "short_org_name",
	"status": "active",
	"updated_by": "sysread"
}

Invite Collaboration members

The PUT endpoint /api/invitations/v1/collaboration_invites can be used to invite members to an existing Collaboration. Use the API Key for the organisation to authenticate:

curl -i -H "Content-Type: application/json" -H "Authorization: Bearer kSOZTmFQuv_rLP5hAOmXwuKO0XGrdq6Fex6qGQ7Igiw" -X PUT -d '{"collaboration_id":14878, "invites":["[email protected]", "[email protected]", "invalid_email"]}' "http://localhost:8080/api/invitations/v1/collaboration_invites"
HTTP/1.0 201 CREATED
["[email protected]","[email protected]"]

The result is a list of emails where an invitation is send to. Optionally a message can be included in the PUT body that will be part of the invitation email. The intended role of the invitees is member.

Clone this wiki locally