Organizations

Organizations are rooted in the /v1/orgs path and are used to group and categorize sub-resources.

Access to resources in the system depends on the access control list set for them. A caller may need to prove its identity by means of an access token passed in the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about retrieving access tokens.

Authorization notes

When creating organizations, the caller must have organizations/create permissions on the current path of the organization or /.

When updating organizations, the caller must have organizations/write permissions on the current path of the organization or /.

When reading organizations, the caller must have organizations/read permissions on the current path of the organization or /.

Create an organization

PUT /v1/orgs/{label}
  {...}

…where {label} is the user friendly name assigned to this organization. The semantics of the label should be consistent with the type of data provided by its sub-resources, since it’ll be a part of the sub-resources’ URI.

Example

Request
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/orgs/myorg" -d \
'{
  "description": "My organization"
}'
Payload
{
  "description": "My organization"
}
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/admin.json"
  ],
  "@id": "https://nexus.example.com/v1/orgs/myorg",
  "@type": "Organization",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T09:58:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Update an organization

This operation overrides the payload.

In order to ensure a client does not perform any changes to an organization without having had seen the previous revision of the organization, the last revision needs to be passed as a query parameter.

PUT /v1/orgs/{label}?rev={previous_rev}
  {...}

… where

  • {previous_rev}: Number - is the last known revision for the organization.
  • {label}: String - is the user friendly name that identifies this organization.

Example

Request
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/orgs/myorg?rev=1" -d \
'{
  "description": "A new description"
}'
Payload
{
  "description": "My organization"
}
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/admin.json"
  ],
  "@id": "https://nexus.example.com/v1/orgs/myorg",
  "@type": "Organization",
  "description": "My organization",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:01:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Deprecate an organization

Locks the organization, so that no further operations can be performed on the resource or on the child resources.

Deprecating an organization is considered to be an update as well. 

DELETE /v1/orgs/{label}?rev={previous_rev}

… where

  • {label}: String - is the user friendly name that identifies this organization.
  • {previous_rev}: Number - is the last known revision for the organization.

Example

Request
curl -XDELETE "https://nexus.example.com/v1/orgs/myorg/tags?rev=3"
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/admin.json"
  ],
  "@id": "https://nexus.example.com/v1/orgs/myorg",
  "@type": "Organization",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:01:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Fetch an organization (current version)

GET /v1/orgs/{label}

…where {label} is the user friendly String name that identifies this organization.

Example

Request
curl "https://nexus.example.com/v1/orgs/myorg"
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/admin.json"
  ],
  "@id": "https://nexus.example.com/v1/orgs/myorg",
  "@type": "Organization",
  "description": "My Organization",
  "_label": "myorg",
  "_uuid": "bc0eba71-2a7f-40e8-ac90-5c97fc6f37d7",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:01:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Fetch an organization (specific version)

GET /v1/orgs/{label}?rev={rev}

… where

  • {rev}: Number - is the revision of the organization to be retrieved.
  • {label}: String - is the user friendly name that identifies this organization.

Example

Request
curl "https://nexus.example.com/v1/orgs/myorg?rev=4"
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/resource.json",
    "https://bluebrain.github.io/nexus/contexts/admin.json"
  ],
  "@id": "https://nexus.example.com/v1/orgs/myorg",
  "@type": "Organization",
  "description": "My Organization",
  "_label": "myorg",
  "_uuid": "bc0eba71-2a7f-40e8-ac90-5c97fc6f37d7",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-18T09:58:00.801Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-18T10:01:00.801Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

List organizations

GET /v1/orgs?from={from}&size={size}&deprecated={deprecated}&rev={rev}&type={type}&createdBy={createdBy}&updatedBy={updatedBy}&label={label}

where…

  • {from}: Number - is the parameter that describes the offset for the current query; defaults to 0
  • {size}: Number - is the parameter that limits the number of results; defaults to 20
  • {deprecated}: Boolean - can be used to filter the resulting organizations based on their deprecation status
  • {rev}: Number - can be used to filter the resulting organizations based on their revision value
  • {type}: Iri - can be used to filter the resulting organizations based on their @type value. This parameter can appear multiple times, filtering further the @type value.
  • {createdBy}: Iri - can be used to filter the resulting organizations based on their creator
  • {updatedBy}: Iri - can be used to filter the resulting organizations based on the person which performed the last update
  • {label}: String - can be used to filter the resulting organizations based on its label. E.g.: label=my will match any organization’s label that contains the string my.

Example

Request
curl "https://nexus.example.com/v1/orgs"
Response
{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/admin.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "_total": 2,
  "_results": [
    {
      "@id": "https://nexus.example.com/v1/orgs/myorg",
      "@type": "Organization",
      "description": "My Organization",
      "_label": "myorg",
      "_uuid": "bc0eba71-2a7f-40e8-ac90-5c97fc6f37d7",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2018-09-18T09:58:00.801Z",
      "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
      "_updatedAt": "2018-09-18T10:01:00.801Z",
      "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
    },
    {
      "@id": "https://nexus.example.com/v1/orgs/myorg2",
      "@type": "Organization",
      "description": "My Second Organization",
      "_label": "myorg2",
      "_uuid": "b42e5206-f81e-430b-808d-5dac2599153d",
      "_rev": 1,
      "_deprecated": false,
      "_createdAt": "2019-01-14T09:29:39.416Z",
      "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
      "_updatedAt": "2019-01-14T09:29:39.416Z",
      "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
    }
  ]
}

Organization Server Sent Events

This endpoint allows clients to receive automatic updates from the organizations in a streaming fashion.

GET /v1/orgs/events

where Last-Event-Id is an optional HTTP Header that identifies the last consumed organization event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.

The response contains a series of organization events, represented in the following way

data:{payload}
event:{type}
id:{id}

where…

  • {payload}: Json - is the actual payload of the current organization
  • {type}: String - is a type identifier for the current organization. Possible types are: OrganizationCreated, OrganizationUpdated and OrganizationDeprecated
  • {id}: String - is the identifier of the organization event. It can be used in the Last-Event-Id HTTP Header

Example

Request
curl "https://nexus.example.com/v1/orgs/events"
Response
data:{"@context":["https://bluebrain.github.io/nexus/contexts/admin.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"OrganizationCreated","description":"l3dd4frl6axlueb organization","_uuid":"3a793ee4-e973-4181-98f5-1eb3ac87d6f6","_label":"l3dd4frl6axlueb","_rev":1,"_instant":"2019-06-14T11:58:46.509Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/test"}
event:OrganizationCreated
id:c3abebd0-8e9b-11e9-81dd-338cb949d9cb

data:{"@context":["https://bluebrain.github.io/nexus/contexts/admin.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"OrganizationCreated","description":"43rl0svyk8fcfki organization","_uuid":"d8ed8e9f-6d4a-4cf7-8f9f-9ed6ed62838c","_label":"43rl0svyk8fcfki","_rev":1,"_instant":"2019-06-14T11:58:53.744Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/test"}
event:OrganizationCreated
id:c7fbe500-8e9b-11e9-81dd-338cb949d9cb

data:{"@context":["https://bluebrain.github.io/nexus/contexts/admin.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"OrganizationUpdated","description":"43rl0svyk8fcfki organization update 1","_uuid":"d8ed8e9f-6d4a-4cf7-8f9f-9ed6ed62838c","_label":"43rl0svyk8fcfki","_rev":2,"_instant":"2019-06-14T11:58:59.458Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/test"}
event:OrganizationUpdated
id:cb680de0-8e9b-11e9-81dd-338cb949d9cb

data:{"@context":["https://bluebrain.github.io/nexus/contexts/admin.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"OrganizationUpdated","description":"43rl0svyk8fcfki organization update 2","_uuid":"d8ed8e9f-6d4a-4cf7-8f9f-9ed6ed62838c","_label":"43rl0svyk8fcfki","_rev":3,"_instant":"2019-06-14T11:59:00.057Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/test"}
event:OrganizationUpdated
id:cbc6a8a0-8e9b-11e9-81dd-338cb949d9cb
        

data:{"@context":["https://bluebrain.github.io/nexus/contexts/admin.json","https://bluebrain.github.io/nexus/contexts/resource.json"],"@type":"OrganizationDeprecated","_uuid":"eb50c21d-3dc7-45e4-94ed-5b2a62f44907","_rev":2,"_instant":"2019-06-14T11:59:05.790Z","_subject":"http://nexus.example.com/v1/realms/nexusdev/users/test"}
event:OrganizationDeprecated
id:cf2d2c30-8e9b-11e9-81dd-338cb949d9cb
0.0.0+1-488ce82a