# Identity REST endpoint
This is a basic endpoint that allows identity management in CzechIdM.

<note tip>  
  * REST endpoint **/api/v1/identities**
  * Identities supported **extended** attributes (**EAV** model)
</note>

# Supports
   * Basic **CRUD** operations (Creating, Reading, Updating, Deleting) and searching.
   * Returns given identity to granted authorities (**/authorities**). 
   * Returns the currently assigned identity role (**/roles**). Specifically, it returns the identity / roles bindings (IdmIdentityRoleDto).
   * Returns the identity of the main position in the organization (**/work-position**). Returned position contains all work position's parents in the tree structure and contract's working position as path.
   * This endpoint also allows you to manage extended identity attributes (EAV).


<note important>If you want to use the REST API, you must be logged in. The easiest way is to use **Basic authentication** directly in request  "- u admin: admin".</note>

# API
** TODO: Swagger**

# Examples

## Creating new identity
You can use the **POST** method to create a new identity. Below is an example of identity creation **new_identity** where the query body contains only "user name, last name, first name and email".
In response is returned whole new created identity (with all audit fields and generated ID).

### Request:
```
curl -i -X POST -H "Content-Type:application/json" -u admin:admin http://localhost:8080/idm-backend/api/v1/identities/ -d '{"username": "john_doe", "firstName": "John", "lastName": "Doe", "email": "john.doe@czechidm.eu"}'
```

### Response:
<code javascript>
{
   "id": "22246775-19be-4088-ab34-cc67a322f731",
   "created": "2017-06-13T09:03:30.127Z",
   "modified": null,
   "creator": "admin",
   "creatorId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
   "modifier": null,
   "modifierId": null,
   "originalCreator": "admin",
   "originalCreatorId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
   "originalModifier": null,
   "originalModifierId": null,
   "username": "new_identity",
   "firstName": "New",
   "lastName": "Identity",
   "email": "new.identity@czechidm.eu",
   "phone": null,
   "titleBefore": null,
   "titleAfter": null,
   "description": null,
   "disabled": false,
   "_trimmed": false,
   "_embedded": {},
   "_links": {"self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/22246775-19be-4088-ab34-cc67a322f731"}}
}
</code>


## Getting authorities for identity
With uses this endpoint, you can get list of authorities for the identity. In this example for **john doe** identity.
Authority defines what the identity potentially can do. For example, if the **IDENTITY_READ** authority is returned, it means that the user will see tab **Users** in the GUI. However, the authorities do not guarantee that the user will see other users as such. This is the task of permissions evaluators.

Edit add tag


### Request:
```
curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/john_doe/authorities'
```

### Response:
<code javascript>
[
  {
    "authority" : "CONTRACTGUARANTEE_AUTOCOMPLETE"
  }, {
    "authority" : "CONTRACTGUARANTEE_PASSWORDCHANGE"
  }, {
    "authority" : "CONTRACTGUARANTEE_READ"
  }, {
    "authority" : "IDENTITYCONTRACT_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITYCONTRACT_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITYCONTRACT_READ"
  }, {
    "authority" : "IDENTITYROLE_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITYROLE_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITYROLE_READ"
  }, {
    "authority" : "IDENTITY_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITY_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITY_READ"
  }, {
    "authority" : "ROLE_AUTOCOMPLETE"
  } 
]
</code>

## Getting assigned roles for identity
With uses this endpoint, you can get list of assigned roles for the identity. In this example for **admin** identity.
For example, a role can assign permissions or accounts on end systems.

<note important>List of returned assigned roles not support pagination. Everytime returning all.</note>

### Request:
```
 curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/admin/roles'

```

### Response:
<code javascript>
{
  "_embedded" : {
    "identityRoles" : [ {
      "id" : "4f2b06cd-5abd-4426-ab52-278741ec8389",
      "created" : "2017-06-12T10:48:42.157Z",
      "modified" : null,
      "creator" : "[SYSTEM]",
      "creatorId" : null,
      "modifier" : null,
      "modifierId" : null,
      "originalCreator" : "[SYSTEM]",
      "originalCreatorId" : null,
      "originalModifier" : null,
      "originalModifierId" : null,
      "identityContract" : "bf843f35-5d31-48e3-9d4d-a224b1ded9de",
      "role" : "2e8d493a-8368-4417-af88-08ad682a2ca1",
      "validFrom" : null,
      "validTill" : null,
      "automaticRole" : false,
      "roleTreeNode" : null,
      "valid" : true,
      "_trimmed" : true,
      "_embedded" : {!Shortened-for-clarity!}
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/idm-backend/api/v1/identities/admin/roles"
    }
  },
  "page" : {
    "size" : 0,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
</code>


## Reading identities
For get identities without filter, you can use the simple GET request show below. The number of identities returned is limited to ** 10 **. You must use pagination to return more results.

### Request:
```
curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/'

```
### Response:
<code javascript>
{
   "_embedded": {"identities":    [
            {
         "id": "7660871b-8b95-4676-87ba-742ffb5ee881",
         "created": "2017-06-12T10:48:46.998Z",
         "modified": "2017-06-12T10:50:44.096Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "john_doe",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john.doe@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "5144d990-3d99-4d2e-8c5e-5335f0c3e67e",
         "created": "2017-06-12T10:48:46.450Z",
         "modified": "2017-06-12T10:52:25.242Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "james_smith",
         "firstName": " James",
         "lastName": "Smith",
         "email": "james.smith@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "a42b0b2a-c4da-4b2d-b4c3-0d82d529e81c",
         "created": "2017-06-12T10:48:45.317Z",
         "modified": "2017-06-12T10:54:54.455Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "richard_miles",
         "firstName": "Richard",
         "lastName": "Miles",
         "email": "richard.miles@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "created": "2017-06-12T10:48:41.397Z",
         "modified": "2017-06-12T10:55:51.328Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "admin",
         "firstName": "Super",
         "lastName": "Admin",
         "email": "admin@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      }
   ]},
   "_links": {"self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?pageu=0&sizeu=3"}},
   "page":    {
      "size": 10,
      "totalElements": 4,
      "totalPages": 1,
      "number": 0
   }
}
</code>

## Reading identities with uses pagination
Below is a example of how to get identity using pagination. We specify page of results by **page** parameter. The **size** parameter defines the number of records on the page. In this case, the first page will be returned, containing only one identity.

### Request:
```
curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1'

```
### Response:
<code javascript>
{
   "_embedded": {"identities": [   {
      "id": "7660871b-8b95-4676-87ba-742ffb5ee881",
      "created": "2017-06-12T10:48:46.998Z",
      "modified": "2017-06-12T10:50:44.096Z",
      "creator": "[SYSTEM]",
      "creatorId": null,
      "modifier": "admin",
      "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
      "originalCreator": "[SYSTEM]",
      "originalCreatorId": null,
      "originalModifier": "admin",
      "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
      "username": "john_doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@czechidm.eu",
      "phone": null,
      "titleBefore": null,
      "titleAfter": null,
      "description": null,
      "disabled": false,
      "_trimmed": true,
      "_embedded": {}
   }]},
   "_links":    {
      "first": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1"},
      "self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1"},
      "next": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=1&size=1"},
      "last": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=3&size=1"}
   },
   "page":    {
      "size": 1,
      "totalElements": 4,
      "totalPages": 4,
      "number": 0
   }
}
</code>

## Get the main identity position in organization
Returns the identity of the main position in the organization (/work-position). Returned position contains all work position's parents in the tree structure and contract's working position as path.

### Request:
```
curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/admin/work-position'

```

### Response:
<code javascript>
{
  "id" : "b34e015f-0a27-45f2-b333-c01478d22f37",
  "created" : "2017-06-13T10:54:18.439Z",
  "modified" : "2017-06-13T10:54:29.956Z",
  "creator" : "admin",
  "creatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "modifier" : "admin",
  "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "originalCreator" : "admin",
  "originalCreatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "originalModifier" : "admin",
  "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "identity" : {
    "id" : "7660871b-8b95-4676-87ba-742ffb5ee881",
    "created" : "2017-06-12T10:48:46.998Z",
    "modified" : "2017-06-12T10:50:44.096Z",
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "modifier" : "admin",
    "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "originalModifier" : "admin",
    "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "username" : "john_doe",
    "firstName" : "John",
    "lastName" : "Doe",
    "email" : "john.doe@czechidm.eu",
    "phone" : null,
    "titleBefore" : null,
    "titleAfter" : null,
    "description" : null,
    "disabled" : false,
    "_trimmed" : false,
    "_embedded" : { }
  },
  "contract" : {
    "id" : "b34e015f-0a27-45f2-b333-c01478d22f37",
    "created" : "2017-06-13T10:54:18.439Z",
    "modified" : "2017-06-13T10:54:29.956Z",
    "creator" : "admin",
    "creatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "modifier" : "admin",
    "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalCreator" : "admin",
    "originalCreatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalModifier" : "admin",
    "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "identity" : "7660871b-8b95-4676-87ba-742ffb5ee881",
    "validFrom" : null,
    "validTill" : null,
    "guarantee" : null,
    "position" : "Director",
    "externe" : false,
    "disabled" : false,
    "main" : true,
    "workPosition" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
    "description" : null,
    "valid" : true,
    "_trimmed" : false,
    "_embedded" : {
      "workPosition" : {
        "id" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
        "created" : "2017-06-12T10:48:47.492Z",
        "modified" : null,
        "creator" : "[SYSTEM]",
        "creatorId" : null,
        "modifier" : null,
        "modifierId" : null,
        "originalCreator" : "[SYSTEM]",
        "originalCreatorId" : null,
        "originalModifier" : null,
        "originalModifierId" : null,
        "code" : "one",
        "name" : "Organization One",
        "parent" : "59f10d91-259e-4fad-8820-39b1607665c8",
        "treeType" : "9920488b-984a-40d0-8af8-108332cc25ab",
        "disabled" : false,
        "_trimmed" : true,
        "_embedded" : {
          "parent" : {
            "id" : "59f10d91-259e-4fad-8820-39b1607665c8",
            "created" : "2017-06-12T10:48:42.706Z",
            "modified" : null,
            "creator" : "[SYSTEM]",
            "creatorId" : null,
            "modifier" : null,
            "modifierId" : null,
            "originalCreator" : "[SYSTEM]",
            "originalCreatorId" : null,
            "originalModifier" : null,
            "originalModifierId" : null,
            "code" : "root",
            "name" : "Root organization",
            "parent" : null,
            "treeType" : "9920488b-984a-40d0-8af8-108332cc25ab",
            "disabled" : false,
            "_trimmed" : true,
            "_embedded" : {
              "treeType" : {
                "id" : "9920488b-984a-40d0-8af8-108332cc25ab",
                "created" : "2017-06-12T10:48:42.587Z",
                "modified" : null,
                "creator" : "[SYSTEM]",
                "creatorId" : null,
                "modifier" : null,
                "modifierId" : null,
                "originalCreator" : "[SYSTEM]",
                "originalCreatorId" : null,
                "originalModifier" : null,
                "originalModifierId" : null,
                "code" : "ORGANIZATIONS",
                "name" : "Organization structure",
                "defaultTreeType" : true,
                "defaultTreeNode" : null,
                "_trimmed" : true,
                "_embedded" : { }
              }
            }
          },
          "treeType" : {
            "id" : "9920488b-984a-40d0-8af8-108332cc25ab",
            "created" : "2017-06-12T10:48:42.587Z",
            "modified" : null,
            "creator" : "[SYSTEM]",
            "creatorId" : null,
            "modifier" : null,
            "modifierId" : null,
            "originalCreator" : "[SYSTEM]",
            "originalCreatorId" : null,
            "originalModifier" : null,
            "originalModifierId" : null,
            "code" : "ORGANIZATIONS",
            "name" : "Organization structure",
            "defaultTreeType" : true,
            "defaultTreeNode" : null,
            "_trimmed" : true,
            "_embedded" : { }
          }
        }
      },
      "identity" : {
        "id" : "7660871b-8b95-4676-87ba-742ffb5ee881",
        "created" : "2017-06-12T10:48:46.998Z",
        "modified" : "2017-06-12T10:50:44.096Z",
        "creator" : "[SYSTEM]",
        "creatorId" : null,
        "modifier" : "admin",
        "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
        "originalCreator" : "[SYSTEM]",
        "originalCreatorId" : null,
        "originalModifier" : "admin",
        "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
        "username" : "john_doe",
        "firstName" : "John",
        "lastName" : "Doe",
        "email" : "john.doe@czechidm.eu",
        "phone" : null,
        "titleBefore" : null,
        "titleAfter" : null,
        "description" : null,
        "disabled" : false,
        "_trimmed" : true,
        "_embedded" : { }
      }
    }
  },
  "path" : [ {
    "id" : "59f10d91-259e-4fad-8820-39b1607665c8",
    "created" : "2017-06-12T10:48:42.706Z",
    "modified" : null,
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "modifier" : null,
    "modifierId" : null,
    "originalModifier" : null,
    "originalModifierId" : null,
    "code" : "root",
    "name" : "Root organization",
    "treeType" : null,
    "disabled" : false,
    "externalId" : null,
    "childrenCount" : 2,
    "parent" : null
  }, {
    "id" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
    "created" : "2017-06-12T10:48:47.492Z",
    "modified" : null,
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "modifier" : null,
    "modifierId" : null,
    "originalModifier" : null,
    "originalModifierId" : null,
    "code" : "one",
    "name" : "Organization One",
    "treeType" : null,
    "disabled" : false,
    "externalId" : null,
    "childrenCount" : 0,
    "parent" : null
  } ],
  "_trimmed" : false,
  "_embedded" : { }
}
</code>