{"id":17190356,"url":"https://github.com/lode/jsonapi-create-additional-relationships-extension","last_synced_at":"2026-03-18T23:56:50.580Z","repository":{"id":178429972,"uuid":"661407456","full_name":"lode/jsonapi-create-additional-relationships-extension","owner":"lode","description":"Create relationships when creating or updating a resource","archived":false,"fork":false,"pushed_at":"2023-07-03T19:52:35.000Z","size":3,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T05:26:30.437Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-02T18:41:01.000Z","updated_at":"2023-07-03T19:53:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"43e9ad42-a278-46ab-a1f7-c702be292dba","html_url":"https://github.com/lode/jsonapi-create-additional-relationships-extension","commit_stats":null,"previous_names":["lode/jsonapi-create-additional-relationships-extension"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lode%2Fjsonapi-create-additional-relationships-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lode%2Fjsonapi-create-additional-relationships-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lode%2Fjsonapi-create-additional-relationships-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lode%2Fjsonapi-create-additional-relationships-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lode","download_url":"https://codeload.github.com/lode/jsonapi-create-additional-relationships-extension/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245407755,"owners_count":20610232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T01:14:03.305Z","updated_at":"2026-01-06T00:05:46.917Z","avatar_url":"https://github.com/lode.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON:API create additional relationships extension\n\nThis extension for [JSON:API](https://jsonapi.org/) allows to create related resources when creating (or updating) a primary resource.\n\nYou can use this extension with the namespace `createAdditional`,\nand the URI `https://github.com/lode/jsonapi-create-additional-relationships-extension`.\n\n- [Why?](#why)\n- [Examples](#examples)\n- [Rules](#rules)\n- [Related](#related)\n\n\n## Why?\n\nIn the JSON:API base specification you can only create a single resource at the time.\nAny relationships to the resource being created already need to exist.\nWhen you need to create both primary resource and relationship resource, you need to make extra API calls.\nWhen both resources require each other to validate, this is impossible.\n\n\n## Examples\n\n### Creating\n\nHere's how to create a primary resource and a related resource in one call.\n\n`POST /persons`:\n\n```json\n{\n\t\"data\": {\n\t\t\"type\": \"Person\",\n\t\t\"attributes\": {\n\t\t\t\"name\": \"Zaphod Beeblebrox\"\n\t\t},\n\t\t\"createAdditional:relationships\": {\n\t\t\t\"starship\": {\n\t\t\t\t\"data\": {\n\t\t\t\t\t\"type\": \"Starship\",\n\t\t\t\t\t\"attributes\": {\n\t\t\t\t\t\t\"name\": \"Heart of Gold\"\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### Updating\n\nSimilarly, you can also create related resources when updating a primary resource in one call.\n\n`PATCH /persons/1`:\n\n```json\n{\n\t\"data\": {\n\t\t\"type\": \"Person\",\n\t\t\"id\": \"1\",\n\t\t\"createAdditional:relationships\": {\n\t\t\t\"semiHalfCousin\": {\n\t\t\t\t\"data\": {\n\t\t\t\t\t\"type\": \"Person\",\n\t\t\t\t\t\"attributes\": {\n\t\t\t\t\t\t\"name\": \"Ford Perfect\"\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### One-to-many relationships\n\nYou can also create (some) resources in one-to-many relationships.\nHere one related resource (Head 1) is already existing, the other needs to be created.\n\n`POST /persons`:\n\n```json\n{\n\t\"data\": {\n\t\t\"type\": \"Person\",\n\t\t\"attributes\": {\n\t\t\t\"name\": \"Zaphod Beeblebrox\"\n\t\t},\n\t\t\"createAdditional:relationships\": {\n\t\t\t\"heads\": [\n\t\t\t\t{\n\t\t\t\t\t\"data\": {\n\t\t\t\t\t\t\"type\": \"Head\",\n\t\t\t\t\t\t\"id\": \"1\"\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"data\": {\n\t\t\t\t\t\t\"type\": \"Head\",\n\t\t\t\t\t\t\"attributes\": {\n\t\t\t\t\t\t\t\"position\": \"below\"\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n\u003e Note: if any other resources were currently related as `heads` to this primary resource,\nthey would be removed, since that's how [regular PATCH calls](https://jsonapi.org/format/#crud-updating-resource-relationships) work.\nIf you don't want that, you can use [regular calls to update a one-to-many relationship](https://jsonapi.org/format/#crud-updating-to-many-relationships).\n\n\n## Rules\n\n### Client requests\n\nA client applying this extension **MUST** use `createAdditional:relationships` as a member of the primary data.\n\nA client **MUST**, for the values in `createAdditional:relationships`, follow the rules for\n[`relationships` in the JSON:API base specification](https://jsonapi.org/format/#document-resource-object-relationships).\nWith one exception, next to resource identifier objects it can use resource objects for related resources that don't exist yet.\n\nA client **MUST** use [resource objects](https://jsonapi.org/format/#document-resource-objects)\nas value for relationships that don't exist yet.\n\nFor these resource objects, a client **MUST NOT** use an `id` which is known to the server, but **MAY** use a client-generated `id`.\nA client **MAY** use a local-id (`lid`) if that is needed for other extensions or profiles, however it is not used by this extension.\n\nA client **MAY** combine resource identifier objects and resource objects in one document or one one-to-many relationship.\n\n### Server processing\n\nA server accepting this extension **MUST** process `createAdditional:relationships` in the same way as the regular `relationships`.\n\nA server **MUST** assume that relationships inside `createAdditional:relationships` without an `id`,\nor with an `id` unknown to the server (e.g. an client-generated `id`),\nare resources that don't exist yet and create new resources for those.\n\nA server **MUST** assume that relationships inside `createAdditional:relationships` with an `id` known to the server,\nare existing resources and not create new resources for those.\n\nA server **MUST NOT** create any resource if one or more of the resources that need to be created can't be created.\n\n\u003e Note: a server may decide to create these resources in any order logical to the server.\n\n### Server responses\n\nA server **MUST** return a `201 Created` also if it makes changes to any of the additional related resources, e.g. assigning an `id`.\n\nA server **SHOULD** return the additionally created resources in the `included` data, unless an `include` query parameter prevents this.\n\nA server **MAY** return a `403 Forbidden` if it doesn't support creating additional resources for the requested primary data or relationship.\n\n### Everything else\n\nThis extension uses the rules of the JSON:API base specification as much as possible.\nThis allows for better compatibility with other extensions and profiles and makes it easier to implement.\n\nFor all rules unspecified, the JSON:API base specification **MUST** be followed. Thus:\n\n- A client **MUST** use an `id` known to the server for resource identifier objects inside `createAdditional:relationships`.\n- A client **MAY** also use the regular `relationships` member and a server **MAY** decide to not support that.\n- A server **MUST** connect all relationships inside `createAdditional:relationships` to the resource in the primary data.\n- A server **MUST** respond to these requests as specified in the JSON:API base specification.\n\n\n## Related\n\n- The bulk create extension: https://github.com/jelhan/json-api-bulk-create-extension\n- The atomic operations extension: https://jsonapi.org/ext/atomic/\n- A php server implementation for jsonapi: https://github.com/lode/jsonapi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flode%2Fjsonapi-create-additional-relationships-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flode%2Fjsonapi-create-additional-relationships-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flode%2Fjsonapi-create-additional-relationships-extension/lists"}