Skip to content

IBX-9452: Describe segment and segment group REST endpoints #2624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: Update importing_assets_from_bundle.md
merged 8 commits into from
Feb 26, 2025
Merged

IBX-9452: Describe segment and segment group REST endpoints #2624

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
73998f8
IBX-9452: Describe segment and segment group endpoints
dabrt Feb 19, 2025
71b57ed
POST and PATCH segment group methods added
dabrt Feb 20, 2025
6afb616
Add endpoint descriptions for segments
dabrt Feb 20, 2025
d263017
Implement review comments
dabrt Feb 25, 2025
4491a33
Upload modified HTML
dabrt Feb 25, 2025
e924724
Move example files and update imports
dabrt Feb 25, 2025
c31c346
Changes after peer review
dabrt Feb 25, 2025
e2786f5
Updated HTML file
dabrt Feb 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .../rest_api/rest_api_reference/input/examples/segment_groups/POST/SegmentGroup.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"SegmentGroup": {
"_media-type": "application/vnd.ibexa.api.SegmentGroup+json",
"_href": "/api/ibexa/v2/segment_groups/segment_group_identifier",
"id": 3,
"identifier": "segment_group_identifier",
"name": "Segment Group Name"
}
}
6 changes: 6 additions & 0 deletions ...i/rest_api/rest_api_reference/input/examples/segment_groups/POST/SegmentGroup.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/segment_group_identifier">
<id>3</id>
<identifier>segment_group_identifier</identifier>
<name>Segment Group Name</name>
</SegmentGroup>
6 changes: 6 additions & 0 deletions ...api/rest_api_reference/input/examples/segment_groups/POST/SegmentGroupCreate.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"SegmentGroupCreate": {
"identifier": "segment_group_identifier",
"name": "Segment Group Name"
}
}
5 changes: 5 additions & 0 deletions ..._api/rest_api_reference/input/examples/segment_groups/POST/SegmentGroupCreate.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentGroupCreate>
<identifier>segment_group_identifier</identifier>
<name>Segment Group Name</name>
</SegmentGroupCreate>
9 changes: 9 additions & 0 deletions ...t_api/rest_api_reference/input/examples/segment_groups/id/PATCH/SegmentGroup.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"SegmentGroup": {
"_media-type": "application/vnd.ibexa.api.SegmentGroup+json",
"_href": "/api/ibexa/v2/segment_groups/modified_segment_group_identifier",
"id": 3,
"identifier": "modified_segment_group_identifier",
"name": "Modified Segment Group Name"
}
}
6 changes: 6 additions & 0 deletions ...st_api/rest_api_reference/input/examples/segment_groups/id/PATCH/SegmentGroup.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/modified_segment_group_identifier">
<id>4</id>
<identifier>modified_segment_group_identifier</identifier>
<name>Modified Segment Group Name</name>
</SegmentGroup>
6 changes: 6 additions & 0 deletions ...rest_api_reference/input/examples/segment_groups/id/PATCH/SegmentGroupUpdate.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"SegmentGroupUpdate": {
"identifier": "modified_segment_group_identifier",
"name": "Modified Segment Group Name"
}
}
5 changes: 5 additions & 0 deletions .../rest_api_reference/input/examples/segment_groups/id/PATCH/SegmentGroupUpdate.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentGroupUpdate>
<identifier>modified_segment_group_identifier</identifier>
<name>Modified Segment Group Name</name>
</SegmentGroupUpdate>
13 changes: 13 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/POST/Segment.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"Segment": {
"_media-type": "application/vnd.ibexa.api.Segment+json",
"_href": "/api/ibexa/v2/segments/segment_identifier",
"id": 3,
"identifier": "segment_identifier",
"name": "Segment Name",
"SegmentGroup": {
"_media-type": "application/vnd.ibexa.api.SegmentGroup+json",
"_href": "/api/ibexa/v2/segment_groups/corporate_accounts"
}
}
}
7 changes: 7 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/POST/Segment.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<Segment media-type="application/vnd.ibexa.api.Segment+xml" href="/api/ibexa/v2/segments/segment_identifier">
<id>3</id>
<identifier>segment_identifier</identifier>
<name>Segment Name</name>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/corporate_accounts"/>
</Segment>
7 changes: 7 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/POST/SegmentCreate.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"SegmentCreate": {
"identifier": "segment_identifier",
"name": "Segment Name",
"group": "corporate_accounts"
}
}
6 changes: 6 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/POST/SegmentCreate.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentCreate>
<identifier>segment_identifier</identifier>
<name>Segment Name</name>
<group>corporate_accounts</group>
</SegmentCreate>
13 changes: 13 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/id/PATCH/Segment.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"Segment": {
"_media-type": "application/vnd.ibexa.api.Segment+json",
"_href": "/api/ibexa/v2/segments/modified_segment_identifier",
"id": 3,
"identifier": "modified_segment_identifier",
"name": "Modified Segment Name",
"SegmentGroup": {
"_media-type": "application/vnd.ibexa.api.SegmentGroup+json",
"_href": "/api/ibexa/v2/segment_groups/small_companies"
}
}
}
7 changes: 7 additions & 0 deletions docs/api/rest_api/rest_api_reference/input/examples/segments/id/PATCH/Segment.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<Segment media-type="application/vnd.ibexa.api.Segment+xml" href="/api/ibexa/v2/segments/modified_segment_identifier">
<id>3</id>
<identifier>modified_segment_identifier</identifier>
<name>Modified Segment Name</name>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/small_companies"/>
</Segment>
7 changes: 7 additions & 0 deletions ...i/rest_api/rest_api_reference/input/examples/segments/id/PATCH/SegmentUpdate.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"SegmentUpdate": {
"identifier": "modified_segment_identifier",
"name": "Modified Segment Name",
"group": "small_companies"
}
}
6 changes: 6 additions & 0 deletions ...pi/rest_api/rest_api_reference/input/examples/segments/id/PATCH/SegmentUpdate.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<SegmentUpdate>
<identifier>modified_segment_identifier</identifier>
<name>Modified Segment Name</name>
<group>small_companies</group>
</SegmentUpdate>
13 changes: 13 additions & 0 deletions ...i/rest_api/rest_api_reference/input/examples/segments/identifier/GET/Segment.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"Segment": {
"_media-type": "application/vnd.ibexa.api.Segment+json",
"_href": "/api/ibexa/v2/segments/segment_identifier",
"id": 3,
"identifier": "segment_identifier",
"name": "Segment Name",
"SegmentGroup": {
"_media-type": "application/vnd.ibexa.api.SegmentGroup+json",
"_href": "/api/ibexa/v2/segment_groups/corporate_accounts"
}
}
}
7 changes: 7 additions & 0 deletions ...pi/rest_api/rest_api_reference/input/examples/segments/identifier/GET/Segment.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<Segment media-type="application/vnd.ibexa.api.Segment+xml" href="/api/ibexa/v2/segments/segment_identifier">
<id>3</id>
<identifier>segment_identifier</identifier>
<name>Segment Name</name>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/corporate_accounts"/>
</Segment>
112 changes: 108 additions & 4 deletions docs/api/rest_api/rest_api_reference/input/ibexa-segment-groups.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,110 @@ get:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
post:
displayName: Create a segment group
description: Creates a segment group.
headers:
Content-Type:
description: A SegmentGroupCreate schema encoded in XML or JSON format.
example: |
application/vnd.ibexa.api.SegmentGroupCreate+xml
application/vnd.ibexa.api.SegmentGroupCreate+json
Accept:
description: A segment group is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.SegmentGroup+xml
application/vnd.ibexa.api.SegmentGroup+json
body:
application/vnd.ibexa.api.SegmentGroupCreate+xml:
type: SegmentGroupCreate
example: !include examples/segment_groups/POST/SegmentGroupCreate.xml.example
application/vnd.ibexa.api.SegmentGroupCreate+json:
type: SegmentGroupCreateWrapper
example: !include examples/segment_groups/POST/SegmentGroupCreate.json.example
responses:
200:
description: OK - list the segment groups.
body:
application/vnd.ibexa.api.SegmentGroup+xml:
type: SegmentGroup
example: !include examples/segment_groups/POST/SegmentGroup.xml.example
application/vnd.ibexa.api.SegmentGroup+json:
type: SegmentGroupWrapper
example: !include examples/segment_groups/POST/SegmentGroup.json.example
400:
description: Error - input data validation failed.
body:
application/vnd.ibexa.api.ErrorMessage+xml:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
401:
description: Error - the user is not authorized to list segment groups.
body:
application/vnd.ibexa.api.ErrorMessage+xml:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
406:
description: Error - input data is not acceptable.
body:
application/vnd.ibexa.api.ErrorMessage+xml:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
/{id}:
patch:
displayName: Update segment group data
description: Updates the segment group's data.
headers:
Content-Type:
description: The SegmentGroupUpdate schema encoded in XML or JSON format.
example: |
application/vnd.ibexa.api.SegmentGroupUpdate+xml
application/vnd.ibexa.api.SegmentGroupUpdate+json
Accept:
description: A segment group is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.SegmentGroup+xml
application/vnd.ibexa.api.SegmentGroup+json
body:
application/vnd.ibexa.api.SegmentGroupUpdate+xml:
type: SegmentGroupUpdate
example: !include examples/segment_groups/id/PATCH/SegmentGroupUpdate.xml.example
application/vnd.ibexa.api.SegmentGroupUpdate+json:
type: SegmentGroupUpdateWrapper
example: !include examples/segment_groups/id/PATCH/SegmentGroupUpdate.json.example
responses:
200:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to be consistent, I imagine the endpoint returns 406 if we were trying to change the identifier to a one that already exists.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope, in such case I am getting 500:
An exception occurred while executing 'UPDATE ibexa_segment_groups SET identifier= ?,name= ? WHEREid = ?' with params [\"Tojesttest7\", \"Modified Segment Group Name\", 6]:\n\nSQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'Tojesttest7' for key 'ibexa_segment_groups.ibexa_segment_groups_identifier'"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so let's not document this 😉

But it's probably a bug - ping @micszo @wiewiurdp

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will check and report.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@micszo @wiewiurdp The same happens for 'UPDATE ibexa_segments after changing identifier to an existing one. 500 is thrown with Integrity constraint violation: 1062 Duplicate entry 'modified_segment_identifier' for key 'ibexa_segments.ibexa_segments_identifier'

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reported as https://issues.ibexa.co/browse/IBX-9634.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately the real issue is in Ibexa\Segmentation\Service\SegmentationService 😞

description: OK - list the segment groups.
body:
application/vnd.ibexa.api.SegmentGroup+xml:
type: SegmentGroup
example: !include examples/segment_groups/id/PATCH/SegmentGroup.xml.example
application/vnd.ibexa.api.SegmentGroup+json:
type: SegmentGroupWrapper
example: !include examples/segment_groups/id/PATCH/SegmentGroup.json.example
delete:
displayName: Delete a segment group
description: Deletes the segment group.
responses:
204:
description: Segment group does not exist.
401:
description: Error - the user is not authorized to delete segment groups.
body:
application/vnd.ibexa.api.ErrorMessage+xml:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
404:
description: Error - the identifier doesn't match any segment group.
body:
application/vnd.ibexa.api.ErrorMessage+xml:
type: ErrorMessage
application/vnd.ibexa.api.ErrorMessage+json:
type: ErrorMessage
/{identifier}:
get:
displayName: Load segment group
Expand All @@ -33,8 +137,8 @@ get:
Accept:
description: If set, the segment group is returned in XML or JSON format.
example: |
vnd.ibexa.api.SegmentGroup+xml
vnd.ibexa.api.SegmentGroup+json
application/vnd.ibexa.api.SegmentGroup+xml
application/vnd.ibexa.api.SegmentGroup+json
responses:
200:
description: OK - return the segment group.
Expand All @@ -57,8 +161,8 @@ get:
Accept:
description: If set, the segment group is returned in XML or JSON format.
example: |
vnd.ibexa.api.SegmentList+xml
vnd.ibexa.api.SegmentList+json
application/vnd.ibexa.api.SegmentList+xml
application/vnd.ibexa.api.SegmentList+json
responses:
200:
description: OK - list the group's segments.
Expand Down
Loading
Loading