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"
}'
Full source at GitHub
Payload
{
  "description": "My organization"
}
Full source at GitHub
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"
}
Full source at GitHub

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"
}'
Full source at GitHub
Payload
{
  "description": "My organization"
}
Full source at GitHub
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"
}
Full source at GitHub

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"
Full source at GitHub
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"
}
Full source at GitHub

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"
Full source at GitHub
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"
}
Full source at GitHub

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"
Full source at GitHub
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"
}
Full source at GitHub

List organizations

GET /v1/orgs?from={from}&size={size}

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

Example

Request
curl "https://nexus.example.com/v1/orgs"
Full source at GitHub
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"
    }
  ]
}
Full source at GitHub