# Create or modify one specific Subject for a specific Label of a specific policy

`PUT /api/2/policies/{policyId}/entries/{label}/subjects/{subjectId}`

Create or modify the subject with ID `subjectId` of the policy identified
by the `policyId` path parameter, and by the `label` path parameter.

Authentication (security requirement alternatives):

```json
[
  {
    "OpenIDConnect": []
  },
  {
    "NginxBasic": []
  },
  {
    "Bearer": []
  }
]
```

- OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
- NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
- Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Parameters:

- `policyId` (path, string, required) - The ID of the policy needs to follow the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)).

The namespace needs to:
* conform to the reverse domain name notation
  Type: string

- `label` (path, string, required) - The label of a policy entry
  Type: string

- `subjectId` (path, string, required) - The ID of an (Authorization) Subject
  Type: string

- `If-Match` (header, string, optional) - The `If-Match` header which has to conform to RFC-7232 (Conditional Requests). Common usages are:
  * optimistic locking by specifying the `ETag` from a previous HTTP response, e.g. `If-Match: "hash:a75ece4e"`
  * retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`
  Type: string

- `If-None-Match` (header, string, optional) - The `If-None-Match` header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying `If-None-Match: *`.
  Type: string

- `if-equal` (header, string, optional) - The `if-equal` header can take the values 'update' (which is the default if omitted), 'skip' or 'skip-minimizing-merge'. If 'update' is defined, the entity will always be updated, even if it is equal before the update. If 'skip' is defined, the entity not be updated if it is equal before the update.  In this case a 'Precondition Failed' 412 status is returned. If 'skip-minimizing-merge' is defined, the entity will not be updated if it is equal before the update.   In this case a 'Precondition Failed' 412 status is returned. Additionally, merge/patch commands will be minimized to only the fields which actually changed, compared to the current state of the entity.
  Type: string
  
  enum: ["update","skip","skip-minimizing-merge"]

- `timeout` (query, string, optional) - Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested
acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or
together with `s`, `ms` or `m` unit. Example: `42s`, `1m`.

The default (if omitted) and maximum timeout is `60s`. A value of `0` applies fire and forget semantics for
the command resulting in setting `response-required=false`.
  Type: string

- `response-required` (query, boolean, optional) - Defines whether a response is required to the API call or not - if set to `false` the response will directly
sent back with a status code of `202` (Accepted).

The default (if ommited) response is `true`.
  Type: boolean

Request body: application/json (required)

JSON representation of the Subject

Type: SubjectEntry

Single (Authorization) Subject entry holding its type.

Schema: [SubjectEntry](https://sourcey-ditto.pages.dev/http-api-doc/models/subjectentry.md)

Example:

```json
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
```

- `type` (required)
  Type: string
  
  The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

- `expiry` (optional)
  Type: string, date-time
  
  The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

- `announcement` (optional)
  Reference: [SubjectAnnouncement](https://sourcey-ditto.pages.dev/http-api-doc/models/subjectannouncement.md); Type: SubjectAnnouncement
  
  Settings for announcements to be made about the subject.
  
  Example:
  
  ```json
  {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "randomizationInterval": "5m"
  }
  ```

Responses:

- 201: The Subject was successfully created.

Content type: application/json

Type: SubjectEntry

Single (Authorization) Subject entry holding its type.

Schema: [SubjectEntry](https://sourcey-ditto.pages.dev/http-api-doc/models/subjectentry.md)

Example:

```json
{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}
```

- `type` (required)
  Type: string
  
  The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

- `expiry` (optional)
  Type: string, date-time
  
  The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.

- `announcement` (optional)
  Reference: [SubjectAnnouncement](https://sourcey-ditto.pages.dev/http-api-doc/models/subjectannouncement.md); Type: SubjectAnnouncement
  
  Settings for announcements to be made about the subject.
  
  Example:
  
  ```json
  {
    "beforeExpiry": "5m",
    "whenDeleted": true,
    "randomizationInterval": "5m"
  }
  ```

- 204: The Subject was successfully updated.

- 400: The request could not be completed. Possible reasons:

  * the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)))
* the JSON body of the policy subject to be created/modified is invalid.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 401: The request could not be completed due to missing authentication.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 403: The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
  You need `WRITE` permission on the root `policy:/entries/{label}/subjects/{subjectId}` resource,
  without any revoke in a deeper path of the policy resource.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 404: The request could not be completed. The policy with the given ID or
the policy entry was not found in the context of the authenticated
user.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 412: A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you
specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of
the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a
failing If-None-Match header for a read request, status 304 will be returned instead.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 413: The created or modified entity is larger than the accepted limit of 100 kB.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

## Examples

### cURL

```bash
curl -X PUT 'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/subjects/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}'
```

### JavaScript

```javascript
const body = `{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/subjects/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "type": "This is some description for this subject, adjust as needed.",
  "expiry": "2020-12-07T11:36:40Z",
  "announcement": {
    "beforeExpiry": "5m",
    "whenDeleted": true
  }
}'''

response = requests.put(
    'https://ditto.eclipseprojects.io/api/2/policies/string/entries/string/subjects/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```