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.
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 to0
{size}
: Number - is the parameter that limits the number of results; defaults to20
{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 stringmy
.
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 theLast-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