Organizations

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

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

copysourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/orgs/myorg"  \
   -d '{"description": "organization description"}'

Response

copysource{
  "@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

copysourcecurl -X PUT \
   -H "Content-Type: application/json" \
   "http://localhost:8080/v1/orgs/myorg?rev=1"  \
   -d '{"description": "organization updated description"}'

Response

copysource{
  "@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

copysourcecurl -X DELETE \
   "http://localhost:8080/v1/orgs/myorg?rev=2"

Response

copysource{
  "@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"
}

Fetch (current version)

GET /v1/orgs/{label}

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

Example

Request

copysourcecurl "http://localhost:8080/v1/orgs/myorg"

Response

copysource{
  "@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

copysourcecurl "http://localhost:8080/v1/orgs/myorg?rev=3"

Response

copysource{
  "@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

copysourcecurl "http://localhost:8080/v1/orgs?label=my"

Response

copysource{
  "@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"
    }
  ]
}

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 event
• {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

copysourcecurl -H "Last-Event-Id: 03d578d0-b194-11eb-9673-bd8b74949729" \
   "http://localhost:8080/v1/orgs/events"

Response

copysourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/organizations.json"],"@type":"OrganizationUpdated","description":"organization updated description","_instant":"2021-05-10T13:31:53.579Z","_label":"myorg","_organizationId":"http://localhost:8080/v1/orgs/myorg","_rev":2,"_subject":"http://localhost:8080/v1/anonymous","_uuid":"2393f414-8fff-4e79-b622-d7a887649952"}
event:OrganizationUpdated
id:1550b8e0-b194-11eb-9673-bd8b74949729

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/organizations.json"],"@type":"OrganizationDeprecated","_instant":"2021-05-10T13:32:31.197Z","_label":"myorg","_organizationId":"http://localhost:8080/v1/orgs/myorg","_rev":3,"_subject":"http://localhost:8080/v1/anonymous","_uuid":"2393f414-8fff-4e79-b622-d7a887649952"}
event:OrganizationDeprecated
id:2bbcc600-b194-11eb-9673-bd8b74949729