External API

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",
    "expiry_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 PUT endpoint api/collaborations_services/v1/connect_collaboration_service can be used to connect an existing Service to an existing Collaboration.

Example input:

{
  "short_name": "coll_short_name",
  "service_entity_id": "https://wiki"
}

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. The required attributes are: short_name and invites.

Authorization: Bearer ${API_KEY}
{
    "short_name": "coll_short_name",
    "intended_role": "member|admin",
    "message": "Optional message included in the invitation...",
    "membership_expiry_date" : 1644015600,
    "invitation_expiry_date" : 1644015600,
    "invites":["[email protected]", "[email protected]", "invalid_email"]
}

The intended_role is either admin or member and determines the role of the user once the invitation is accepted. It defaults to member. The optional membership_expiry_date determines the expiration date of the collaboration membership once the invitation is accepted. The optional invitation_expiration_date determines de expiration date of the invitation. It defaults to 14 days.

The result returns all invitations send. The invitation_id can be used to request the status of an invitation.

  "invitations": [
    { 
      "email": "[email protected]", 
      "invitation_expiry_date": 1644015600,
      "status": "open"
      "invitation_id": "26d04b61-7540-44c4-9060-0927973f1156"
    }, { ... } 
  ]
}