Outdated version

You are browsing the docs for Nexus v1.10.x, the latest release is available here

Organizations

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

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 /.

Please visit Authentication & authorization section to learn more about it.

Payload

{
  "description": "{description}"
}

…where {description} as an optional String providing some descriptive information about the organization.

Create

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
sourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/orgs/myorg"  \
   -d '{"description": "organization description"}'
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_label": "myorg",
  "_rev": 1,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:31:24.223Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

Update

This operation overrides the organization payload (description field).

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
sourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/orgs/myorg?rev=1"  \
   -d '{"description": "organization updated description"}'
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_label": "myorg",
  "_rev": 2,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:31:53.579Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

Deprecate

Locks the organization, so that no further operations can be performed on the organization 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
sourcecurl -X DELETE \
   "http://localhost:8080/v1/orgs/myorg?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_label": "myorg",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:32:31.197Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

Undeprecate

Reverses the deprecation of an organisation.

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

PUT /v1/orgs/{label}/undeprecate?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
sourcecurl -X PUT \
   "http://localhost:8080/v1/orgs/myorg/undeprecate?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": false,
  "_label": "myorg",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:32:31.197Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

Delete

Permanently delete an organization containing no projects. If there is a project, returns 409 Conflict.

The caller must have organizations/delete permissions.

DELETE /v1/orgs/{label}?prune=true

… where

  • {label}: String - is the user friendly name that identifies this organization.
  • prune: a flag to make permanent deletion explicit. To avoid mistakes, if prune=true then rev cannot be present and a 400 Bad Request will be returned.

Example

Request
sourcecurl -X DELETE \
   "http://localhost:8080/v1/orgs/myorg?prune=true"

Fetch (current version)

GET /v1/orgs/{label}

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

Example

Request
sourcecurl "http://localhost:8080/v1/orgs/myorg"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "description": "organization updated description",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_label": "myorg",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:32:31.197Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

Fetch (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
sourcecurl "http://localhost:8080/v1/orgs/myorg?rev=3"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/organizations.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/orgs/myorg",
  "@type": "Organization",
  "description": "organization updated description",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
  "_createdAt": "2021-05-10T13:31:24.223Z",
  "_createdBy": "http://localhost:8080/v1/anonymous",
  "_deprecated": true,
  "_label": "myorg",
  "_rev": 3,
  "_self": "http://localhost:8080/v1/orgs/myorg",
  "_updatedAt": "2021-05-10T13:32:31.197Z",
  "_updatedBy": "http://localhost:8080/v1/anonymous",
  "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
}

List

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

where…

  • {from}: Number - the offset from which to start the listings. Defaults to 0
  • {size}: Number - the maximum amount fo results to be returned. Defaults to 30
  • {deprecated}: Boolean - filter the resulting organizations based on their deprecation status. Optional parameter.
  • {rev}: Number - filter the resulting organizations based on their revision value. Optional parameter.
  • {createdBy}: Iri - filter the resulting organizations based on their creator. Optional parameter.
  • {updatedBy}: Iri - filter the resulting organizations based on the person which performed the last update. Optional parameter.
  • {label}: String - filter the resulting organizations based on its label. E.g.: label=my will match any organization’s label that contains the string my. Optional parameter.
  • {sort}: String - orders the resulting organizations based on its metadata fields. Optional parameter that can appear multiple times, further specifying the ordering criteria. Defaults to _createdAt, ordering organizations by creation date.

Example

Request
sourcecurl "http://localhost:8080/v1/orgs?label=my"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/organizations.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "http://localhost:8080/v1/orgs/myorg",
      "@type": "Organization",
      "description": "organization updated description",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/organizations.json",
      "_createdAt": "2021-05-10T13:31:24.223Z",
      "_createdBy": "http://localhost:8080/v1/anonymous",
      "_deprecated": true,
      "_label": "myorg",
      "_rev": 3,
      "_self": "http://localhost:8080/v1/orgs/myorg",
      "_updatedAt": "2021-05-10T13:32:31.197Z",
      "_updatedBy": "http://localhost:8080/v1/anonymous",
      "_uuid": "2393f414-8fff-4e79-b622-d7a887649952"
    }
  ]
}
v1.10.x