Package co.ankatech.keymanagement.client.keymanagement.api

Class KeyRotationScheduleApi

java.lang.Object
co.ankatech.keymanagement.client.keymanagement.api.KeyRotationScheduleApi
public class KeyRotationScheduleApi extends Object

  • Constructor Details

    • KeyRotationScheduleApi

      public KeyRotationScheduleApi()

    • KeyRotationScheduleApi

      public KeyRotationScheduleApi(ApiClient apiClient)

  • Method Details

    • getApiClient

      public ApiClient getApiClient()

    • setApiClient

      public void setApiClient(ApiClient apiClient)

    • getHostIndex

      public int getHostIndex()

    • setHostIndex

      public void setHostIndex(int hostIndex)

    • getCustomBaseUrl

      public String getCustomBaseUrl()

    • setCustomBaseUrl

      public void setCustomBaseUrl(String customBaseUrl)

    • getKeyRotationScheduleCall

      public okhttp3.Call getKeyRotationScheduleCall(@Nonnull UUID tenantId, @Nonnull String kid, ApiCallback _callback) throws ApiException
      Build call for getKeyRotationSchedule
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      _callback - Callback for upload/download progress
      Returns:
      Call to execute
      Throws:
      ApiException - If fail to serialize the request body object

    • getKeyRotationSchedule

      public KeyRotationScheduleView getKeyRotationSchedule(@Nonnull UUID tenantId, @Nonnull String kid) throws ApiException
      Get the key's rotation schedule Returns the key's effective automatic-rotation schedule. <p><b>Enablement</b> is per key and opt-in: a key whose schedule was never set reads `autoRotationEnabled: false` and `state: DISABLED`. <b>Triggers</b> are the key's own override (`source: KEY_ASSIGNED`), else the tenant default (`TENANT_ASSIGNED`), else the deployment default (`DEPLOYMENT`).</p> <p><b>State.</b> `NOT_ROTATABLE` when the key cannot be rotated in its current state (revoked, archived, pending destruction, or refused by the tenant's lifecycle policy), whatever its schedule; otherwise `DISABLED`, `NO_CADENCE` (enabled but no interval applies; only a usage option can rotate it) or `SCHEDULED`.</p> <p><b>Usage options.</b> `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` say whether the key rotates when its usage count reaches its soft usage limit, or its maximum usage limit; they act only while `autoRotationEnabled` is true, and a key whose schedule was never set reads both `false`.</p> <p><b>Next rotation.</b> `nextDueAt` is set only when `state` is `SCHEDULED`. It is the activation of the key's primary material (`baseInstant`) plus the configured interval, brought forward by the earlier of two bounds — the deployment maximum interval from the same base, and the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6) from the creation of the primary material — and never earlier than `effectiveFrom`, the newest instant at which one of the composed policies took effect — except that it never passes the end of the key's maximum cryptoperiod, an absolute obligation: then it may lie in the past and the key is overdue. `clampedBy` names the bound that applied and `effectiveInterval` the interval used. Intervals are ISO-8601 durations (ISO 8601-1:2019 §5.5.2): the period is added on the UTC calendar, then the time part of hours and minutes. `toleranceWindow` is one hundredth of `effectiveInterval`, measured from `baseInstant` on the UTC calendar, at most `PT6H`: raising `nextDueAt` to `effectiveFrom` does not widen it.</p> <p><b>Licence.</b> When the licence server cannot provide the deployment licence, the read still answers: the ceiling applies every catalogue pack, the shorter side, and reports `ceiling.basis: LICENCE_UNRESOLVED`.</p> <p>Required scope: `admin.keys.rotation-schedule.read`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      Returns:
      KeyRotationScheduleView
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • getKeyRotationScheduleWithHttpInfo

      public ApiResponse<KeyRotationScheduleView> getKeyRotationScheduleWithHttpInfo(@Nonnull UUID tenantId, @Nonnull String kid) throws ApiException
      Get the key's rotation schedule Returns the key's effective automatic-rotation schedule. <p><b>Enablement</b> is per key and opt-in: a key whose schedule was never set reads `autoRotationEnabled: false` and `state: DISABLED`. <b>Triggers</b> are the key's own override (`source: KEY_ASSIGNED`), else the tenant default (`TENANT_ASSIGNED`), else the deployment default (`DEPLOYMENT`).</p> <p><b>State.</b> `NOT_ROTATABLE` when the key cannot be rotated in its current state (revoked, archived, pending destruction, or refused by the tenant's lifecycle policy), whatever its schedule; otherwise `DISABLED`, `NO_CADENCE` (enabled but no interval applies; only a usage option can rotate it) or `SCHEDULED`.</p> <p><b>Usage options.</b> `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` say whether the key rotates when its usage count reaches its soft usage limit, or its maximum usage limit; they act only while `autoRotationEnabled` is true, and a key whose schedule was never set reads both `false`.</p> <p><b>Next rotation.</b> `nextDueAt` is set only when `state` is `SCHEDULED`. It is the activation of the key's primary material (`baseInstant`) plus the configured interval, brought forward by the earlier of two bounds — the deployment maximum interval from the same base, and the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6) from the creation of the primary material — and never earlier than `effectiveFrom`, the newest instant at which one of the composed policies took effect — except that it never passes the end of the key's maximum cryptoperiod, an absolute obligation: then it may lie in the past and the key is overdue. `clampedBy` names the bound that applied and `effectiveInterval` the interval used. Intervals are ISO-8601 durations (ISO 8601-1:2019 §5.5.2): the period is added on the UTC calendar, then the time part of hours and minutes. `toleranceWindow` is one hundredth of `effectiveInterval`, measured from `baseInstant` on the UTC calendar, at most `PT6H`: raising `nextDueAt` to `effectiveFrom` does not widen it.</p> <p><b>Licence.</b> When the licence server cannot provide the deployment licence, the read still answers: the ceiling applies every catalogue pack, the shorter side, and reports `ceiling.basis: LICENCE_UNRESOLVED`.</p> <p>Required scope: `admin.keys.rotation-schedule.read`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      Returns:
      ApiResponse<KeyRotationScheduleView>
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • getKeyRotationScheduleAsync

      public okhttp3.Call getKeyRotationScheduleAsync(@Nonnull UUID tenantId, @Nonnull String kid, ApiCallback<KeyRotationScheduleView> _callback) throws ApiException
      Get the key's rotation schedule (asynchronously) Returns the key's effective automatic-rotation schedule. <p><b>Enablement</b> is per key and opt-in: a key whose schedule was never set reads `autoRotationEnabled: false` and `state: DISABLED`. <b>Triggers</b> are the key's own override (`source: KEY_ASSIGNED`), else the tenant default (`TENANT_ASSIGNED`), else the deployment default (`DEPLOYMENT`).</p> <p><b>State.</b> `NOT_ROTATABLE` when the key cannot be rotated in its current state (revoked, archived, pending destruction, or refused by the tenant's lifecycle policy), whatever its schedule; otherwise `DISABLED`, `NO_CADENCE` (enabled but no interval applies; only a usage option can rotate it) or `SCHEDULED`.</p> <p><b>Usage options.</b> `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` say whether the key rotates when its usage count reaches its soft usage limit, or its maximum usage limit; they act only while `autoRotationEnabled` is true, and a key whose schedule was never set reads both `false`.</p> <p><b>Next rotation.</b> `nextDueAt` is set only when `state` is `SCHEDULED`. It is the activation of the key's primary material (`baseInstant`) plus the configured interval, brought forward by the earlier of two bounds — the deployment maximum interval from the same base, and the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6) from the creation of the primary material — and never earlier than `effectiveFrom`, the newest instant at which one of the composed policies took effect — except that it never passes the end of the key's maximum cryptoperiod, an absolute obligation: then it may lie in the past and the key is overdue. `clampedBy` names the bound that applied and `effectiveInterval` the interval used. Intervals are ISO-8601 durations (ISO 8601-1:2019 §5.5.2): the period is added on the UTC calendar, then the time part of hours and minutes. `toleranceWindow` is one hundredth of `effectiveInterval`, measured from `baseInstant` on the UTC calendar, at most `PT6H`: raising `nextDueAt` to `effectiveFrom` does not widen it.</p> <p><b>Licence.</b> When the licence server cannot provide the deployment licence, the read still answers: the ceiling applies every catalogue pack, the shorter side, and reports `ceiling.basis: LICENCE_UNRESOLVED`.</p> <p>Required scope: `admin.keys.rotation-schedule.read`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      _callback - The callback to be executed when the API call finishes
      Returns:
      The request call
      Throws:
      ApiException - If fail to process the API call, e.g. serializing the request body object

    • listKeyRotationExecutionsCall

      public okhttp3.Call listKeyRotationExecutionsCall(@Nonnull UUID tenantId, @Nonnull String kid, @Nullable Integer page, @Nullable Integer size, ApiCallback _callback) throws ApiException
      Build call for listKeyRotationExecutions
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      page - Zero-based page of executions (optional, default to 0)
      size - Executions per page, 1 to 100 (optional, default to 20)
      _callback - Callback for upload/download progress
      Returns:
      Call to execute
      Throws:
      ApiException - If fail to serialize the request body object

    • listKeyRotationExecutions

      public KeyRotationExecutionsResponse listKeyRotationExecutions(@Nonnull UUID tenantId, @Nonnull String kid, @Nullable Integer page, @Nullable Integer size) throws ApiException
      List a key's automatic rotation executions Returns the key's automatic-rotation schedule as the scheduling service holds it and one page of its executions, latest due first: the next planned rotation, and every past one with its result. <p>Only the key's own rotation obligation is returned. A key whose automatic rotation was never configured answers 200 with no `schedule` and an empty page. A rotation requested by hand is not a scheduled execution and is not listed: read the key's material versions for every rotation.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      page - Zero-based page of executions (optional, default to 0)
      size - Executions per page, 1 to 100 (optional, default to 20)
      Returns:
      KeyRotationExecutionsResponse
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • listKeyRotationExecutionsWithHttpInfo

      public ApiResponse<KeyRotationExecutionsResponse> listKeyRotationExecutionsWithHttpInfo(@Nonnull UUID tenantId, @Nonnull String kid, @Nullable Integer page, @Nullable Integer size) throws ApiException
      List a key's automatic rotation executions Returns the key's automatic-rotation schedule as the scheduling service holds it and one page of its executions, latest due first: the next planned rotation, and every past one with its result. <p>Only the key's own rotation obligation is returned. A key whose automatic rotation was never configured answers 200 with no `schedule` and an empty page. A rotation requested by hand is not a scheduled execution and is not listed: read the key's material versions for every rotation.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      page - Zero-based page of executions (optional, default to 0)
      size - Executions per page, 1 to 100 (optional, default to 20)
      Returns:
      ApiResponse<KeyRotationExecutionsResponse>
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • listKeyRotationExecutionsAsync

      public okhttp3.Call listKeyRotationExecutionsAsync(@Nonnull UUID tenantId, @Nonnull String kid, @Nullable Integer page, @Nullable Integer size, ApiCallback<KeyRotationExecutionsResponse> _callback) throws ApiException
      List a key's automatic rotation executions (asynchronously) Returns the key's automatic-rotation schedule as the scheduling service holds it and one page of its executions, latest due first: the next planned rotation, and every past one with its result. <p>Only the key's own rotation obligation is returned. A key whose automatic rotation was never configured answers 200 with no `schedule` and an empty page. A rotation requested by hand is not a scheduled execution and is not listed: read the key's material versions for every rotation.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      page - Zero-based page of executions (optional, default to 0)
      size - Executions per page, 1 to 100 (optional, default to 20)
      _callback - The callback to be executed when the API call finishes
      Returns:
      The request call
      Throws:
      ApiException - If fail to process the API call, e.g. serializing the request body object

    • replaceKeyRotationScheduleCall

      public okhttp3.Call replaceKeyRotationScheduleCall(@Nonnull UUID tenantId, @Nonnull String kid, @Nonnull KeyRotationScheduleRequest keyRotationScheduleRequest, ApiCallback _callback) throws ApiException
      Build call for replaceKeyRotationSchedule
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      keyRotationScheduleRequest - The key's schedule: the enablement, the optional cadence override, the optional usage options and the optional version last read. (required)
      _callback - Callback for upload/download progress
      Returns:
      Call to execute
      Throws:
      ApiException - If fail to serialize the request body object

    • replaceKeyRotationSchedule

      public KeyRotationScheduleView replaceKeyRotationSchedule(@Nonnull UUID tenantId, @Nonnull String kid, @Nonnull KeyRotationScheduleRequest keyRotationScheduleRequest) throws ApiException
      Replace the key's rotation schedule Full replacement (PUT) of the key's schedule. <p><b>Body.</b> `autoRotationEnabled` is required. `triggers` is optional: absent or null inherits the tenant default, or the deployment default when the tenant has none; an array is the key's own cadence — at most one `TIME_BASED` trigger whose `interval` is an ISO-8601 duration (ISO 8601-1:2019 §5.5.2) of years, months and days with an optional time part of hours and minutes (`P90D`, `PT2M`, `P1DT12H`), shorter or longer than the inherited default — and an empty array sets no cadence for the key. `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` are optional booleans: absent or null is false, and the stored value is replaced. `version` is optional: when sent and no longer current, the write is refused with 409 and nothing is stored.</p> <p><b>Shortest interval.</b> After its grammar, an interval shorter than the deployment's shortest interval is refused with 400 `rotation-interval-below-floor`, whose `extensions.floor` states it. That floor is `P1D` unless a development deployment lowers it; an interval it cannot exceed from any start, such as `P1M`, is admitted. The refusal comes before the ceilings below, and a stored interval is always read back and scheduled as stored.</p> <p><b>Usage options.</b> Each acts only while `autoRotationEnabled` is true: the key is rotated when its usage count reaches its soft usage limit (`rotateOnSoftUsageLimit`) or its maximum usage limit (`rotateOnUsageExhaustion`). An option this write turns on (stored false or absent) is refused with 422 `usage-rotation-without-soft-limit` when the key's current material has no soft usage limit, or 422 `usage-rotation-without-usage-limit` when it has no maximum usage limit. False is always accepted. An option stored before a later change removed the limit is kept and acts on nothing; sending it again as true is not a change, so it does not refuse the rest of the write.</p> <p><b>Enabling needs a cadence or a usage option.</b> Enabling a key whose effective triggers carry no interval is admitted when a usage option is true (state `NO_CADENCE`, no `nextDueAt`); with neither it is refused with 422 (`rotation-schedule-without-cadence`).</p> <p><b>Ceilings.</b> A per-key interval is refused with 422 (`rotation-interval-exceeds-ceiling`) when it is longer than the deployment `maxInterval`; than the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6); or, on a compliance-locked deployment, than the locked deployment default — a shorter interval and disabling are accepted. Comparisons hold from any start date. Reading the compliance maximum needs the deployment licence; when the licence server cannot provide it the write answers 502 and stores nothing.</p> <p><b>Versioning.</b> A changed schedule, a usage option included, stores a new version: `policyVersions.key` increases by one and the key's effective instant is the instant of this write, so no rotation becomes due before it. A body equal to the stored schedule — or disabling a key that has none — changes nothing and writes no audit record. Every change is recorded as one signed admin audit event attributed to the key's tenant.</p> <p>The response is the key's effective schedule, as the read returns it. Required scope: `admin.keys.rotation-schedule.write`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      keyRotationScheduleRequest - The key's schedule: the enablement, the optional cadence override, the optional usage options and the optional version last read. (required)
      Returns:
      KeyRotationScheduleView
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • replaceKeyRotationScheduleWithHttpInfo

      public ApiResponse<KeyRotationScheduleView> replaceKeyRotationScheduleWithHttpInfo(@Nonnull UUID tenantId, @Nonnull String kid, @Nonnull KeyRotationScheduleRequest keyRotationScheduleRequest) throws ApiException
      Replace the key's rotation schedule Full replacement (PUT) of the key's schedule. <p><b>Body.</b> `autoRotationEnabled` is required. `triggers` is optional: absent or null inherits the tenant default, or the deployment default when the tenant has none; an array is the key's own cadence — at most one `TIME_BASED` trigger whose `interval` is an ISO-8601 duration (ISO 8601-1:2019 §5.5.2) of years, months and days with an optional time part of hours and minutes (`P90D`, `PT2M`, `P1DT12H`), shorter or longer than the inherited default — and an empty array sets no cadence for the key. `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` are optional booleans: absent or null is false, and the stored value is replaced. `version` is optional: when sent and no longer current, the write is refused with 409 and nothing is stored.</p> <p><b>Shortest interval.</b> After its grammar, an interval shorter than the deployment's shortest interval is refused with 400 `rotation-interval-below-floor`, whose `extensions.floor` states it. That floor is `P1D` unless a development deployment lowers it; an interval it cannot exceed from any start, such as `P1M`, is admitted. The refusal comes before the ceilings below, and a stored interval is always read back and scheduled as stored.</p> <p><b>Usage options.</b> Each acts only while `autoRotationEnabled` is true: the key is rotated when its usage count reaches its soft usage limit (`rotateOnSoftUsageLimit`) or its maximum usage limit (`rotateOnUsageExhaustion`). An option this write turns on (stored false or absent) is refused with 422 `usage-rotation-without-soft-limit` when the key's current material has no soft usage limit, or 422 `usage-rotation-without-usage-limit` when it has no maximum usage limit. False is always accepted. An option stored before a later change removed the limit is kept and acts on nothing; sending it again as true is not a change, so it does not refuse the rest of the write.</p> <p><b>Enabling needs a cadence or a usage option.</b> Enabling a key whose effective triggers carry no interval is admitted when a usage option is true (state `NO_CADENCE`, no `nextDueAt`); with neither it is refused with 422 (`rotation-schedule-without-cadence`).</p> <p><b>Ceilings.</b> A per-key interval is refused with 422 (`rotation-interval-exceeds-ceiling`) when it is longer than the deployment `maxInterval`; than the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6); or, on a compliance-locked deployment, than the locked deployment default — a shorter interval and disabling are accepted. Comparisons hold from any start date. Reading the compliance maximum needs the deployment licence; when the licence server cannot provide it the write answers 502 and stores nothing.</p> <p><b>Versioning.</b> A changed schedule, a usage option included, stores a new version: `policyVersions.key` increases by one and the key's effective instant is the instant of this write, so no rotation becomes due before it. A body equal to the stored schedule — or disabling a key that has none — changes nothing and writes no audit record. Every change is recorded as one signed admin audit event attributed to the key's tenant.</p> <p>The response is the key's effective schedule, as the read returns it. Required scope: `admin.keys.rotation-schedule.write`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      keyRotationScheduleRequest - The key's schedule: the enablement, the optional cadence override, the optional usage options and the optional version last read. (required)
      Returns:
      ApiResponse<KeyRotationScheduleView>
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • replaceKeyRotationScheduleAsync

      public okhttp3.Call replaceKeyRotationScheduleAsync(@Nonnull UUID tenantId, @Nonnull String kid, @Nonnull KeyRotationScheduleRequest keyRotationScheduleRequest, ApiCallback<KeyRotationScheduleView> _callback) throws ApiException
      Replace the key's rotation schedule (asynchronously) Full replacement (PUT) of the key's schedule. <p><b>Body.</b> `autoRotationEnabled` is required. `triggers` is optional: absent or null inherits the tenant default, or the deployment default when the tenant has none; an array is the key's own cadence — at most one `TIME_BASED` trigger whose `interval` is an ISO-8601 duration (ISO 8601-1:2019 §5.5.2) of years, months and days with an optional time part of hours and minutes (`P90D`, `PT2M`, `P1DT12H`), shorter or longer than the inherited default — and an empty array sets no cadence for the key. `rotateOnSoftUsageLimit` and `rotateOnUsageExhaustion` are optional booleans: absent or null is false, and the stored value is replaced. `version` is optional: when sent and no longer current, the write is refused with 409 and nothing is stored.</p> <p><b>Shortest interval.</b> After its grammar, an interval shorter than the deployment's shortest interval is refused with 400 `rotation-interval-below-floor`, whose `extensions.floor` states it. That floor is `P1D` unless a development deployment lowers it; an interval it cannot exceed from any start, such as `P1M`, is admitted. The refusal comes before the ceilings below, and a stored interval is always read back and scheduled as stored.</p> <p><b>Usage options.</b> Each acts only while `autoRotationEnabled` is true: the key is rotated when its usage count reaches its soft usage limit (`rotateOnSoftUsageLimit`) or its maximum usage limit (`rotateOnUsageExhaustion`). An option this write turns on (stored false or absent) is refused with 422 `usage-rotation-without-soft-limit` when the key's current material has no soft usage limit, or 422 `usage-rotation-without-usage-limit` when it has no maximum usage limit. False is always accepted. An option stored before a later change removed the limit is kept and acts on nothing; sending it again as true is not a change, so it does not refuse the rest of the write.</p> <p><b>Enabling needs a cadence or a usage option.</b> Enabling a key whose effective triggers carry no interval is admitted when a usage option is true (state `NO_CADENCE`, no `nextDueAt`); with neither it is refused with 422 (`rotation-schedule-without-cadence`).</p> <p><b>Ceilings.</b> A per-key interval is refused with 422 (`rotation-interval-exceeds-ceiling`) when it is longer than the deployment `maxInterval`; than the maximum cryptoperiod the entitled compliance packs state for the key's class (NIST SP 800-57 Part 1 Rev. 5 §5.3.6); or, on a compliance-locked deployment, than the locked deployment default — a shorter interval and disabling are accepted. Comparisons hold from any start date. Reading the compliance maximum needs the deployment licence; when the licence server cannot provide it the write answers 502 and stores nothing.</p> <p><b>Versioning.</b> A changed schedule, a usage option included, stores a new version: `policyVersions.key` increases by one and the key's effective instant is the instant of this write, so no rotation becomes due before it. A body equal to the stored schedule — or disabling a key that has none — changes nothing and writes no audit record. Every change is recorded as one signed admin audit event attributed to the key's tenant.</p> <p>The response is the key's effective schedule, as the read returns it. Required scope: `admin.keys.rotation-schedule.write`.</p>
      Parameters:
      tenantId - Tenant UUID (required)
      kid - Stable key id (required)
      keyRotationScheduleRequest - The key's schedule: the enablement, the optional cadence override, the optional usage options and the optional version last read. (required)
      _callback - The callback to be executed when the API call finishes
      Returns:
      The request call
      Throws:
      ApiException - If fail to process the API call, e.g. serializing the request body object