Related data operations

Request type: POST

Format: {{baseurl}}/api/default/{{entity}}({{item_to_add_related_content_to_id}})/{{related_data_field_name}}/$ref

To create an item relation, you need to make a POST request to the desired content item, which has a related data field you want to populate. In the URL you also need to specify the related data field name, using the /{{related_data_field_name}}/$ref endpoint. In the request body you must specify the web service URL to the item you want to relate in JSON format using the @odata.idparameter, similar to: { "@odata.id":"{{baseurl}}/api/default/{{entity}}({{item_to_relate_id}})" }.

For example, if you have a “RelatedImages” related media field for your news items, and you want to relate an image to one of your news items you must make a POST request to http://mysite.com/api/default/newsitems(d004c824-e22e-4037-9550-489f373b28c1)/RelatedImages/$ref . In the body of the request specify {"@odata.id" : "http://mysite.com/api/default/images(45cf53e4-1f0a-4f3f-9bd3-c880b5dbeb7c)"}.

Request type: GET

Format: {{baseurl}}/api/default/{{entity}}({{item_id}})/{{related_data_field_name}}

To get the value of the related data field you must specify the entity type and the item Id, and pass the related data field name. For example, if you have a RelatedImages related media field for your news items, and you want to get the related images for a news items you must say: http://mysite.com/api/default/newsitems(d004c824-e22e-4037-9550-489f373b28c1)/RelatedImages. This service call will return only the related images, not the news item itself. If you want to return both the item and its related data items you must use the $expandsystem query option, described below.

Request type: GET

Format: {{baseurl}}/api/default/{{entity}}({{item_id}})$expand={{related_data_field_name}}

You can use the $expand system query option to include the related data information along with the retrieved content item.

When using Multisite, If the related data field is of type related media (images, videos, files) and you defined its Source property to be "Default site source", you need to pass an additional parameter to make the service call execute in the context of the current site. This is necessary because when the “Default site source” option is selected, the related data field needs to resolve the default media content provider for the current site, however the requests to the web services are not executed in the context of a site. For more information on setting the Source property of related media fields check: Add a Related media custom field.

To make the service call execute in the context of a site, you must use the sf_site parameter in the following format: {{baseurl}}/api/default/{{entity}}({{item_id}})sf_site={{site_id}}&$expand={{related_data_field_name}}. Consider the following example:

1. You have two sites – Site A and Site B
2. You have a dynamic module called Press Releases, with a related images field called PRImage.
3. When creating the PRImage field, you have specified its Source property to be "Default site source".
4. In Site A you have created several Press release items, and uploaded an image in the PRImage field for each of the items.
5. You have shared the Press Releases module with Site B.
6. Site B has been configured to use a default provider for media content, different than the one for Site A (the default option when creating a new site)
7. When you go to the Press Releases module in Site B and access some of the shared Press release items form Site A, you will not see the related image, because the default media content provider for this site is different, and it does not contain the related images.
8. If you want to display the Press releases from Site A on the Site B frontend, together with their related image, you need to make the following service call: http://siteadomain.com/api/default/pressreleases?sf_site={{Site_A_Id}}&$expand=PRImage

Request type: DELETE

Format: {{baseurl}}/api/default/{{entity}}({{item_id}})/{{related_data_field_name}}({{related_item_id}})/$ref

To delete a related item, you must send a DELETE request to the same endpoint used to access the related data item, namely /{{related_data_field_name}}({{related_item_id}})/$ref. For example, to delete one of the images related to a news item through the RelatedImages field, you must say:  http://mysite.com/api/default/newsitems(d004c824-e22e-4037-9550-489f373b28c1)/RelatedImages(45cf53e4-1f0a-4f3f-9bd3-c880b5dbeb7c)/$ref