From 3094279bc9f3ffbbbe73a85b29d85b7934491dd1 Mon Sep 17 00:00:00 2001 From: Bodhert Date: Tue, 1 Jul 2025 13:59:16 -0500 Subject: [PATCH 1/5] before giving an ai review --- documentation/topics/relationships.md | 100 ++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/documentation/topics/relationships.md b/documentation/topics/relationships.md index d6f3e50f..11e5dc65 100644 --- a/documentation/topics/relationships.md +++ b/documentation/topics/relationships.md @@ -73,6 +73,106 @@ Non-map argument types, e.g `argument :author, :integer` (expecting an author id JSON:API, because it expects `{"type": _type, "id" => id}` for relationship values. To support non-map arguments in `relationship_arguments`, instead of `:author`, use `{:id, :author}`. This works for `{:array, _}` type arguments as well, so the value would be a list of ids. + +## Creating related resources without the id +This is useful for those who want to create relationship, without create them +in two separatated api calls and be associated with an Id, this is an escape +hatch of doing the previous and is not open api spec compatible +le, but is totally +possible + +```elixir +# With a post route that references the `leads` argument, this will mean that +# locations will have the ability to create a Lead resource when called from +# the api + json_api do + routes do + base_route "/location", Marketplace.Location do + post :create, relationship_arguments: [:leads] + end + + base_route "/lead", Marketplace.Lead do + post :create + end + end + end + + +# in leads resource you will have the following + actions do + create :create do + primary?(true) + accept([:type, :description, :priority, :location_id]) + end + end + + relationships do + belongs_to :location, Marketplace.Location + end + +# in Location you will have the following: + + actions do + create :create do + primary?(true) + accept([:name, :location, :images]) + argument(:leads, {:array, :map}, allow_nil?: false) + + change(manage_relationship(:leads, type: :create)) + end + end + + + relationships do + has_many :leads, ProjectX.Marketplace.Lead + end +``` + +this way, when requesting to create a location, leads will be automatically be created + +```json +{ + "data": { + "type": "location", + "attributes": { + "name": "Test Lead", + "location": { + "lat": 32323, + "long": 23232, + "address": "dsdsds" + }, + "images": ["url1", "url2", "url3"] + }, + "relationships": { + "leads": { + "data": [ + { + "type": "lead", + "meta": { + "type": "Roof", + "description": "roofing has 3 holes to fix", + "priority": "high" + } + }, + { + "type": "lead", + "meta": { + "type": "garden", + "description": "Garden looks like it could be polsih", + "priority": "medium" + } + } + ] + } + } + } +} +``` + +be aware that the `"relationships"` field in the response will be empty, since we are not following open api spec convention, but if you check in your data storage +the data should be there + + ## Relationship Manipulation Routes You can also specify routes that are dedicated to manipulating relationships. We generally suggest the above approach, but JSON:API spec also allows for dedicated relationship routes. For example: From df18b3c08ec7286ba7695b8190b79e3f2974f55d Mon Sep 17 00:00:00 2001 From: Bodhert Date: Tue, 1 Jul 2025 14:05:25 -0500 Subject: [PATCH 2/5] fact checking and enhancing with ai --- documentation/topics/relationships.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/documentation/topics/relationships.md b/documentation/topics/relationships.md index 11e5dc65..f5cf35a3 100644 --- a/documentation/topics/relationships.md +++ b/documentation/topics/relationships.md @@ -75,16 +75,13 @@ instead of `:author`, use `{:id, :author}`. This works for `{:array, _}` type ar ## Creating related resources without the id -This is useful for those who want to create relationship, without create them -in two separatated api calls and be associated with an Id, this is an escape -hatch of doing the previous and is not open api spec compatible -le, but is totally -possible + +This feature is useful for creating relationships without requiring two separate API calls and without needing to associate resources with an ID first. This is an escape hatch from the standard approach and is not JSON:API spec compliant, but it is completely possible to implement. ```elixir # With a post route that references the `leads` argument, this will mean that -# locations will have the ability to create a Lead resource when called from -# the api +# locations will have the ability to create Lead resources when called from +# the API json_api do routes do base_route "/location", Marketplace.Location do @@ -98,7 +95,7 @@ possible end -# in leads resource you will have the following +# In the leads resource you will have the following: actions do create :create do primary?(true) @@ -110,7 +107,7 @@ possible belongs_to :location, Marketplace.Location end -# in Location you will have the following: +# In the Location resource you will have the following: actions do create :create do @@ -128,18 +125,18 @@ possible end ``` -this way, when requesting to create a location, leads will be automatically be created +This way, when requesting to create a location, leads will be automatically created as well. ```json { "data": { "type": "location", "attributes": { - "name": "Test Lead", + "name": "Test Location", "location": { "lat": 32323, "long": 23232, - "address": "dsdsds" + "address": "test street 123" }, "images": ["url1", "url2", "url3"] }, @@ -158,7 +155,7 @@ this way, when requesting to create a location, leads will be automatically be c "type": "lead", "meta": { "type": "garden", - "description": "Garden looks like it could be polsih", + "description": "Garden looks like it could be polished", "priority": "medium" } } @@ -169,8 +166,7 @@ this way, when requesting to create a location, leads will be automatically be c } ``` -be aware that the `"relationships"` field in the response will be empty, since we are not following open api spec convention, but if you check in your data storage -the data should be there +Be aware that the `"relationships"` field in the response will be empty, since we are not following JSON:API spec conventions, but if you check your data storage, the data should be there. ## Relationship Manipulation Routes From e7b2e0bcc2fcf44e827250d3b9c692c8fc0ceb2a Mon Sep 17 00:00:00 2001 From: Bodhert Date: Tue, 1 Jul 2025 14:10:51 -0500 Subject: [PATCH 3/5] removing typo --- documentation/topics/relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/topics/relationships.md b/documentation/topics/relationships.md index f5cf35a3..f33c0886 100644 --- a/documentation/topics/relationships.md +++ b/documentation/topics/relationships.md @@ -121,7 +121,7 @@ This feature is useful for creating relationships without requiring two separate relationships do - has_many :leads, ProjectX.Marketplace.Lead + has_many :leads, Marketplace.Lead end ``` From ccac80ac11abab65ce4881118888a894c525ce71 Mon Sep 17 00:00:00 2001 From: Bodhert Date: Tue, 1 Jul 2025 18:25:49 -0500 Subject: [PATCH 4/5] adding note and link the json api doc --- documentation/topics/relationships.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/topics/relationships.md b/documentation/topics/relationships.md index f33c0886..54a74150 100644 --- a/documentation/topics/relationships.md +++ b/documentation/topics/relationships.md @@ -166,8 +166,7 @@ This way, when requesting to create a location, leads will be automatically crea } ``` -Be aware that the `"relationships"` field in the response will be empty, since we are not following JSON:API spec conventions, but if you check your data storage, the data should be there. - +Note that the related data won't be returned unless included with the include query parameter. For the JSON:API specification on the include parameter, see [https://jsonapi.org/format/#fetching-includes](https://jsonapi.org/format/#fetching-includes). ## Relationship Manipulation Routes From 1e59e91e806e533f8f68c6945eb6b4542fdfa41b Mon Sep 17 00:00:00 2001 From: Bodhert Date: Tue, 1 Jul 2025 18:31:13 -0500 Subject: [PATCH 5/5] typo --- documentation/topics/relationships.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/topics/relationships.md b/documentation/topics/relationships.md index 54a74150..8c70f0c5 100644 --- a/documentation/topics/relationships.md +++ b/documentation/topics/relationships.md @@ -166,7 +166,7 @@ This way, when requesting to create a location, leads will be automatically crea } ``` -Note that the related data won't be returned unless included with the include query parameter. For the JSON:API specification on the include parameter, see [https://jsonapi.org/format/#fetching-includes](https://jsonapi.org/format/#fetching-includes). +Note that the related data won't be returned unless included with the include query parameter. For the JSON:API specification on the include parameter, see [json api fetching includes](https://jsonapi.org/format/#fetching-includes). ## Relationship Manipulation Routes