Skip to content

External API

Jump to bottom
Okke Harsta edited this page Dec 28, 2021 · 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. The required attributes are: name, description, short_name, disable_join_requests, disclose_member_information, disclose_email_information, administrators.

Authorization: Bearer ${API_KEY}
{
    "name": "new_collaboration",
    "description": "a description of the new CO",
    "administrators": ["[email protected]", "[email protected]"],
    "message": "Please join...",
    "short_name": "new_short_name",
    "expiration_date" : 1644015600,
    "logo": "/9j/4AAQSkZJRgABA...",
    "website_url": "https://web.nl",
    "disable_join_requests": true,
    "disclose_email_information": true,
    "disclose_member_information": true,

}

The optional logo is the base64 encoded binary image. The expiration_date is the UNIX epoch divided by 1000. The admin of the Collaboration is one of the admins of the Organisation. The response:

{
    "collaboration_memberships_count": 0,
    "created_at": 1640681285.0,
    "created_by": "urn:harry",
    "description": "Description",
    "disable_join_requests": true,
    "disclose_email_information": true,
    "disclose_member_information": true,
    "expiry_date": 1644015600.0,
    "global_urn": "uuc:new_short_name",
    "id": 5558,
    "identifier": "1c810012-b89b-4541-9336-19fab8951f3a",
    "invitations_count": 1,
    "last_activity_date": 1640681285.0,
    "logo": "http://localhost:8080/api/images/collaborations/df49667f-769f-432d-95b6-ea310f0eec1d",
    "name": "new_collaboration",
    "organisation_id": 4072,
    "short_name": "new_short_name",
    "status": "active",
    "updated_by": "urn:harry",
    "uuid4": "df49667f-769f-432d-95b6-ea310f0eec1d",
    "website_url": "https://web.nl"
}

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 '{"short_name":"coll_short_name", "service_entity_id":"https://wiki"}' "http://localhost:8080/api/collaborations_services/v1/connect_collaboration_service"
HTTP/1.0 201 CREATED

{
  "status": "connected|pending",
  "collaboration": {
    "organisation_short_name": "some_org",
    "short_name": "coll_short_name",
   }
  "service": {
    "entity_id": "http://wiki",
  }
}

If the service does not allow automatic collaboration connections, then a service connection request is send to the service owners.The returned status is pending. Note for this to work there must be at least one admin user in the collaboration.

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 ${API_KEY}" -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 too. 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