Copy page

Migrating from v1

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. For platform weekly/manual schedules and time slots, use 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.
• 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

Related Guides

• Configuration Resources
• Platform Schedule Configuration
• Write Semantics
• Querying Lists