ApiUser

The ApiUser resource has one public URL. (For information about the difference between Public and Internal URLs and HATEOAS conventions, please see API Structure and Conventions.)

/v1/api_users

Structure

username

(String) The username of the ApiUser

real_name

(String) The real name of the ApiUser.

email

(String) The email address of the ApiUser. (User-facing clients could/should of course use this to display a Gravatar.)

authentication_duration

(Integer) Controls how long the Authentications of this ApiUser are to be valid. Defaults to 1800 (half an hour).

login_blocked

(Boolean) If false (the default), the ApiUser may authenticate. If true, a 403 Login blocked will be returned.

login_blocked_reason

(String or Null) If present, this reason string will be returned in the _api_error body of a blocked login attempt.

indestructible

(Boolean, read only) If present and true, the ApiUser can't be destroyed.

created_at

(String) A datetime string in GMT.

updated_at

(String) A datetime string in GMT.

{
 "api_user": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/api_users/99651e97-6a76-4b16-b500-7e8bcbfc72cd",
              "type": "application/json" },
            "authentications": { ... },
            "roles": { ... },
            "groups": { ... },
            "connect": { ... },
            "creator": { ... },
            "updater": { ... }
          },
          "username": "fozzie_the_bear",
          "real_name": "Fozzie",
          "email": "fozzie@muppets.com",
          "authentication_duration": 1800,
          "login_blocked": true,
          "login_blocked_reason": "You have been a very bad bear. Please reflect on this for a day or two.",
          "created_at": "2012-12-03T18:40:53Z",
          "updated_at": "2012-12-03T18:40:53Z",
          "lock_version": 12
  }
}

Please note that you should not draw any conclusions from the perceived structure of the URLs, nor should you construct URLs based upon any inferences you make. For more information, refer to API Structure and Conventions.

Hyperlinks

The following hyperlink names are used in the following subsections. To retrieve the URL and Content-Type to use, use the _links hash. Note that the URI may change, and thus you should make no inference on how to construct similar URIs from any previous URI. For more information, refer to Hyperlink URIs are Opaque. You may store hyperlink URIs in permanent storage for later use.

The hyperlinks for a ApiUser resource are:

self

as always, the self hyperlink can be used to perform CRUD actions on the ApiUser resource.

authentications

GET retrieves the collection of Authentications belonging to this ApiUser.

roles

GET retrieves the collection of Roles this ApiUser has.

groups

GET retrieves the collection of Groups to which this ApiUser belongs.

rights

GET retrieves the collection of all Rights the ApiUser has through their roles and groups.

connect

PUT with the query arg href=uri to connect the two resources. The uri is the URL encoded value of the href attribute of the other object's self link. (The body should be empty.)

DELETE with the query arg href=uri to disconnect the two resources. The uri is the URL encoded value of the href attribute of the other object's self link.

When connections are made or broken, ApiUsers affected by the change in effective Rights will have their Authentications deleted and their associated authorisations invalidated. The effect is immediate, which means they will have to reauthorise (transparently or otherwise).

creator

GET retrieves the ApiUser who created this ApiUser.

updater

GET retrieves the ApiUser who last updated this ApiUser.

GET self

Retrieves an ApiUser resource.

200

The operation was successful.

PUT self

Updates an ApiUser resource. The attribute password is optional: if present, the password will be salted and encrypted and used in subsequent authentications. The password cannot be retrieved in any subsequent operations, not even by Ocean operators and developers.

PUT requests, according to the RFC standard, require all resource attributes to be updated simultaneously. However, in Ocean PUT requests have the same semantics as PATCH requests in that it's possible to set individual attributes. The API will reject requests with missing essential attributes. If you receive unknown properties, you must preserve them and pass them back unchanged in PUT and PATCH requests. Other than that, you should ignore them. This enables the API to be upgraded transparently.

200

The operation was successful.

DELETE self

Deletes an ApiUser resource, and also deletes all its Authentications, invalidating their authorisations. This takes immediate effect.

204

The delete operation was successful.

GET /v1/api_users

Returns a collection of ApiUsers. The basic URL returns all ApiUsers in the system. You can add query arguments to the basic URL to perform matches and substring searches, and you can also group on a property.

You can match and group on the following properties:

• username
• real_name
• email

The following returns all ApiUsers whose username property is bozo:

GET /v1/api_users?username=bozo

You can also search on substrings in email by using search, for instance to weed out pædophiles:

GET /v1/api_users?search=holyvatican

Pagination can also be performed using page:

GET /v1/api_users?page=3

The first page is 0. Page size defaults to 25, but can be changed using page_size:

GET /v1/api_users?page=0&page_size=100

200

The operation was successful. The collection is returned as a JSON array in the response body.

POST /v1/api_users

Creates a new ApiUser resource. In addition to the attributes given above, the attribute password is required: the password will be salted and hashed and used in subsequent authentications. Once submitted, the password cannot be retrieved, not even by Ocean operators and developers.

201

The operation was successful and a new ApiUser resource has been created. The response headers will, as is customary, include a standard Location header giving the URI of the newly created resource. To save you the extra request Ocean also returns the new ApiUser resource in the response body.