Users API

Introduction

This document details the end points related to the users management of the OBM provisioning system.

The default exchange format is JSON.

Naming

In this document we take /provisioning/{apiVersion}/{domainUUID} as the base URI of REST end points. This path will be called {baseURI} in the rest of the document. The notation {serverBaseURL} represents the root URL of the REST server, e.g.: http://1.2.3.4:8080/ The notation {batchId} represents a unique batch identifier The notation {userId} represents a unique user identifier The notation {apiVersion} represents a string linking to the version of the API that the client want to use (e.g.: "v1") The notation {domainUUID} represents the universally unique identifier of the domain we're currently working on

Data types and structures

datetime

The datetime data type is the complete representation, extended format of ISO 8601:2004.

User

    {

      // Mandatory fields

      id: string, // userobm_ext_id
      login: string, // userobm_login
      lastname: string, // userobm_lastname
      profile: string, // userobm_perms

      // Optional fields
     // The following fields can be ommitted in PATCH,PUT and POST requests

      firstname: string, // userobm_firstname
      commonname: string, // userobm_commonname
      password: string, // userobm_password, only PLAIN supported
      kind: string, // userobm_kind
      title: string, // userobm_title
      description: string, // userobm_description
      company: string, // userobm_company
      service: string, // userobm_service
      direction: string, // userobm_direction
      addresses: [string], // userobm_address1, 2 and 3, only 3 addresses supported
      town: string, // userobm_town
      zipcode: string, // userobm_zipcode
      business_zipcode: string, // userobm_expresspostal
      country: string, // userobm_country_iso3166 
      phones: [string], // userobm_phone1 and 2, only 2 phone numbers supported
      mobile: string, // userobm_mobile
      faxes: [string], // userobm_fax1 and 2, only 2 fax numbers supported
      archived: boolean, // userobm_archive
      mail_quota: integer, // userobm_mail_quota, default 0 (no quota)
      mail_server: string, // host.host_name, with the corresponding host_id assigned to userobm_mail_server_id
      mails: [string], // a list of emails, with or without domain
      hidden: boolean, // userobm_hidden
      timecreate: datetime, // time of creation in the OBM database - field ignored for PUT/POST/PATCH
      timeupdate: datetime, // time of update in the OBM database - field ignored for PUT/POST/PATCH
     groups: [{ "id": {groupId}, "url": string }, {}, ...], // list of group identifiers and URLs - this is a read-only attribute and is ignored for PUT/PATCH/POST requests
     delegation: string, // delegation of user in OBM (http://obm.org/wiki/delegation-administration)
     delegation_target: string, // delegation target of user in OBM
     nomad_allowed: boolean, // give right to user to activate nomad option
     nomad_enabled: boolean, // enable / disable nomade option
     nomad_local_copy: boolean, // make a copy of mail localy
     nomad_mail: string // define redirection address
    }

The password field in the JSON stream might be hashed depending on the configuration of the OBM server.

Create a user

Definition

This endpoint creates a new user.

REST information

• method: POST
• uri: {baseURI}/batches/{batchId}/users
• query string parameters: none
• request body: a User data structure
• return code: 201 Created on success, 4XX on data format problems, 5xx on errors

• return HTTP header:

  Location: {serverBaseURL}/provisioning/{apiVersion}/users/{userId}
  

• returned content on success: none

• returned content On error: see "standard errors"

Modify a user

Definition

This endpoint modifies a user. This operation replaces the user completely, with the information given in the request. To partially modify some attributes of a user, see patching a user.

REST information

• method: PUT
• uri: {baseURI}/batches/{batchId}/users/{userId}
• query string parameters: none
• request body: a User data structure
• return code: 200 on success, 4XX on data format problems, 404 on a non existing {userId}, 5xx on errors
• returned content on success: none
• returned content on error: see "standard errors"

Patching a user

Definition

This endpoint modifies a user, adding or replacing fields using a partial representation of the user. To replace a user, see Modify a user.

REST information

• method: PATCH
• uri: {baseURI}/batches/{batchId}/users/{userId}
• query string parameters: none
• request body: a (partial) User data structure
• return code: 200 on success, 4XX on data format problems, 404 on a non existing {userId}, 5xx on errors
• returned content on success: none
• returned content on error: see "standard errors"

Archive or delete a user

Definition

This endpoint archives or deletes a user, depending on a query parameter.

REST information

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}/users/{userId}
• query string parameters:

• return code: 200 on success, 5xx on errors, 404 on a non existing {userId}
• returned content on success: none
• returned content on error: see "standard errors"

Representation of the user

Definition

The objective of this end point is to get the representation of a user in the database.

REST information

• method: GET
• endpoint: {baseURI}/users/{userId}
• query string parameters: none
• return code: 200 on success, 5xx on errors, 404 on a non existing {userId}
• returned content on success: a User data structure
• returned content on error: see "standard errors"

Listing all users

Definition

This endpoint returns a list of all users.

REST information

• method: GET
• endpoint: {baseURI}/users/
• query string parameters: none
• return code: 200 on success, 5xx on errors

• returned content on

  {
      users: [{ "id": {userId}, "url": string }, {}, ...] // List of user identifiers and URLs
  }
  

• returned content on error: see "standard errors"

Womens Running Shoes & Running Clothes