# Configuration Resource Migration

This page covers v1-to-v2 migration notes for platform, group, category, type, status, and
task-format resources.

For the v2-native resource model, start with
[Configuration Resources](/docs/guides/resource-guides/configuration-resources). For platform weekly/manual schedules and
time slots, use [Platform Schedule Configuration](/docs/guides/resource-guides/platform-schedule-configuration). Exact
schemas, examples, status codes, and field-level omission or `null` semantics remain in the
generated API reference.

## Endpoint Mapping

| v1 usage pattern | v2 direction |
|------------------|--------------|
| `GET .../groups/` or `GET .../platforms/` returning an array | Use the v2 list endpoint and parse the shared pagination shape. |
| `GET .../{resource}/by-external/{externalId}` | Use `GET /api/v2/{resource}/external-id/{externalId}` for groups, platforms, categories, and types. |
| `GET .../categories/` or `GET .../types/` as global lists | Use platform-scoped lists: `/api/v2/platforms/{platformId}/categories` or `/api/v2/platforms/{platformId}/types`. |
| `POST .../categories/` with `platform` in the body | Use `POST /api/v2/platforms/{platformId}/categories`; send `parentCategoryId` only for a subcategory. |
| `POST .../types/` with `platform` in the body | Use `POST /api/v2/platforms/{platformId}/types`; the platform is taken from the path. |
| `GET .../formats` | Use `GET /api/v2/task-formats`. |
| `GET .../element-status`, `.../publication-status`, `.../task-status` | Use plural v2 paths: `/api/v2/element-statuses`, `/api/v2/publication-statuses`, and `/api/v2/task-statuses`. |
| `GET .../publication-status/platform/{platformId}` | Use `GET /api/v2/publication-statuses/platform/{platformId}`. |

## List And Lookup Changes

Groups, platforms, statuses, task formats, platform-scoped categories, and platform-scoped types use
the shared v2 list response shape. v1 clients that parse bare arrays must update list parsers to
read `content`, `size`, `hasMore`, and pagination metadata.

Client-impacting lookup changes:

- use `page` or `cursor` according to [Querying Lists](/docs/guides/api-conventions/querying-lists).
- use `active` only on status and task-format lists.
- use `includeDeleted` only where the API reference exposes it.
- replace `/by-external/{externalId}` paths with `/external-id/{externalId}` where exposed.
- persist the returned v2 `id` for future writes whenever possible.

## Write Model Changes

Common configuration write resources use explicit write DTOs instead of accepting response bodies as
payloads.

| Resource | Create | Replace | Patch |
|----------|--------|---------|-------|
| Group | `name`, optional `externalId`, optional `parentGroupId` | `name`, optional `externalId` | presence-aware `name` and `externalId` |
| Platform | `name` plus platform fields and optional schedule fields | full replacement, including required platform fields | presence-aware patch; schedule fields follow platform schedule rules |
| Category | platform ID in path, `name`, optional `externalId`, optional `parentCategoryId` | `name`, optional `externalId`, required `parentCategoryId` field that can be `null` | presence-aware `name`, `externalId`, and `parentCategoryId` |
| Type | platform ID in path, `name`, optional `externalId` | `name`, optional `externalId` | presence-aware `name` and `externalId` |

Important migration points:

- group, platform, category, and type create operations return `201 Created`.
- group and platform create responses include a `Location` header.
- `PUT` is full replacement; required fields must be present.
- `PATCH` is presence-aware; omitted fields remain unchanged.
- `externalId: null` clears the external ID where documented.
- category and type create no longer send `platform` in the JSON body; the platform is addressed in
  the URL.

## Category And Type Placement

Categories and types belong to a publication platform.

For categories:

- list and create categories through `/api/v2/platforms/{platformId}/categories`.
- use `parentCategoryId` to create or move a subcategory.
- `parentCategoryId: null` means top-level placement where the operation documents it.
- existing top-level categories cannot be moved under another parent through `PUT` or `PATCH`; send
  `parentCategoryId: null` on `PUT`, or omit it on `PATCH`.
- only top-level categories can be used as parents.

For types:

- list and create types through `/api/v2/platforms/{platformId}/types`.
- update a persisted type through `/api/v2/types/{id}`.
- update and patch payloads do not move a type to another platform.

## Delete Behavior

| Resource | Immediate v2 response | Deferred v2 response | Migration impact |
|----------|-----------------------|----------------------|------------------|
| Group | `204 No Content` | `202 Accepted` with a message body | Stop assuming v1-style `200 OK`; handle deferred deletion where returned. |
| Platform | `204 No Content` | `202 Accepted` with a message body | Stop assuming v1-style `200 OK`; handle deferred deletion where returned. |
| Category | `204 No Content` | `202 Accepted` with a message body | Refresh affected element state because category delete can remove linked publications. |
| Type | `204 No Content` | Not exposed | Stop expecting a delete response body. |

## Statuses And Task Formats

:::caution{title="Read-only in public v2"}

Statuses and task formats are read-only through the public API. Use these endpoints to find
IDs and metadata for element, task, and publication write payloads; do not migrate v1-style
administration writes to these public endpoints.

:::

## Related Guides

- [Configuration Resources](/docs/guides/resource-guides/configuration-resources)
- [Platform Schedule Configuration](/docs/guides/resource-guides/platform-schedule-configuration)
- [Write Semantics](/docs/guides/api-conventions/write-semantics)
- [Querying Lists](/docs/guides/api-conventions/querying-lists)