# API Documentation

### Overview

The Directory Changes API allows developers to retrieve changes (delta changes) for different types of resources in a directory service. This API is useful for keeping track of user, group, and membership changes in a system, especially in scenarios where on-premises synchronization is involved.

<figure><img src="https://1332728329-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlMTU9Uyx5cjbGdcEsR3N%2Fuploads%2FkLvlJESQx0d11htpzvAs%2Fimage.png?alt=media&#x26;token=5a8d219a-6031-4735-a2d6-ed9af6bd4ac9" alt=""><figcaption><p>Architectural diagram – how it could work with a Runbook using Azure Automation</p></figcaption></figure>

### Base URL

The base endpoint for this API is:

```
https://api.servicechanger.com/public/directory-changes
```

### Authentication

All API requests require authentication using an API key that should be included in the request headers.

```
x-api-key: YOUR_API_KEY
```

### Endpoints

#### Get Delta Changes for Resources

Retrieves changes (created, updated, deleted) for specified resource types since a given timestamp.

```
GET /public/directory-changes
```

**Query Parameters**

| Parameter             | Type          | Required | Description                                                                         |
| --------------------- | ------------- | -------- | ----------------------------------------------------------------------------------- |
| onPremisesSyncEnabled | boolean       | Yes      | Filter for resources that have on-premises sync enabled or disabled                 |
| lastSyncDate          | string        | No       | ISO timestamp to retrieve changes that occurred after this date                     |
| resourceType          | string (enum) | Yes      | Type of resource to get changes for. Possible values: `user`, `group`, `membership` |

**Request Headers**

| Header    | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| x-api-key | string | Yes      | API key for authentication |

**Response**

**Status Code: 200 (Success)**

```json
{
  "data": [
    {
      "resourceType": "user",
      "resource": {
        // User properties (see Resource Models below)
      },
      "changeType": "created",
      "timestamp": "2023-05-15T14:30:00Z",
      "onPremisesSyncEnabled": true
    },
    // Additional change records...
  ],
  "message": "Delta changes fetched successfully",
  "statusCode": 200
}
```

**Status Code: 400 (Bad Request)**

Returned when the request is invalid or missing required parameters.

### Resource Models

The API deals with three main resource types:

#### User Resource

Represents user entities in the system.

| Property                     | Type          | Description                                    |
| ---------------------------- | ------------- | ---------------------------------------------- |
| id                           | string (UUID) | Unique identifier for the user                 |
| displayName                  | string        | The display name of the user                   |
| department                   | string        | Department the user belongs to                 |
| jobTitle                     | string        | User's job title                               |
| businessPhones               | string\[]     | List of business phone numbers                 |
| surname                      | string        | Last name of the user                          |
| givenName                    | string        | First name of the user                         |
| accountEnabled               | boolean       | Whether the user account is enabled            |
| userPrincipalName            | string        | Principal name used for authentication         |
| onPremisesDomainName         | string        | Domain name for on-premises AD (if applicable) |
| onPremisesSamAccountName     | string        | SAM account name for on-premises AD            |
| onPremisesSecurityIdentifier | string        | Security identifier for on-premises AD         |
| onPremisesLastSyncDateTime   | string        | Timestamp of last sync with on-premises AD     |
| onPremisesUserPrincipalName  | string        | UPN for on-premises AD                         |

#### Group Resource

Represents group entities in the system.

<table><thead><tr><th width="302">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string (UUID)</td><td>Unique identifier for the group</td></tr><tr><td>displayName</td><td>string</td><td>The display name of the group</td></tr><tr><td>created</td><td>string</td><td>Timestamp when the group was created</td></tr><tr><td>description</td><td>string</td><td>Description of the group</td></tr><tr><td>mailNickname</td><td>string</td><td>Mail nickname for the group (if applicable)</td></tr><tr><td>mailEnabled</td><td>boolean</td><td>Whether mail is enabled for this group</td></tr><tr><td>onPremisesSyncEnabled</td><td>boolean</td><td>Whether this group syncs with on-premises AD</td></tr><tr><td>onPremisesSamAccountName</td><td>string</td><td>SAM account name for on-premises AD</td></tr><tr><td>onPremisesNetBiosName</td><td>string</td><td>NetBIOS name for on-premises AD</td></tr><tr><td>onPremisesDomainName</td><td>string</td><td>Domain name for on-premises AD</td></tr><tr><td>onPremisesSecurityIdentifier</td><td>string</td><td>Security identifier for on-premises AD</td></tr><tr><td>onPremisesLastSyncDateTime</td><td>string</td><td>Timestamp of last sync with on-premises AD</td></tr></tbody></table>

#### Membership Resource

Represents membership relationships between users and groups.

| Property | Type          | Description                       |
| -------- | ------------- | --------------------------------- |
| userId   | string (UUID) | ID of the user in the membership  |
| groupId  | string (UUID) | ID of the group in the membership |

### Change Types

The API tracks three types of changes:

| Change Type | Description                       |
| ----------- | --------------------------------- |
| created     | A new resource was created        |
| updated     | An existing resource was modified |
| deleted     | A resource was removed            |

### Example Requests

#### Get All User Changes Since Last Sync

```bash
curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=true&resourceType=user&lastSyncDate=2023-05-01T00:00:00Z' \
  -H 'x-api-key: your-api-key'
```

#### Get All Group Changes

```bash
curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=false&resourceType=group' \
  -H 'x-api-key: your-api-key'
```

#### Get All Membership Changes

```bash
curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=true&resourceType=membership&lastSyncDate=2023-06-01T00:00:00Z' \
  -H 'x-api-key: your-api-key'
```

### Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request:

| Status Code | Description                                               |
| ----------- | --------------------------------------------------------- |
| 200         | OK - The request was successful                           |
| 400         | Bad Request - The request was invalid or cannot be served |
| 401         | Unauthorized - API key is missing or invalid              |

### Best Practices

1. **Efficient Syncing**: Use the `lastSyncDate` parameter to only retrieve changes since your last synchronization.
2. **Rate Limiting**: Implement appropriate rate limiting in your client applications to prevent API throttling and ensure consistent service availability.
3. **Error Handling**: Implement robust error handling to manage API failures gracefully.
4. **Authentication**: Please keep your API key secure and store it in any key-value solutions such as vault.
