Skip to content

IBX-9058: Complete REST API Reference #2674

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
merged 20 commits into from
May 15, 2025
Merged

IBX-9058: Complete REST API Reference #2674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
9750d11
REST API: Continue user/users/{userId}/segments
adriendupuis Mar 14, 2025
fef7031
ibexa-user-users.raml: Fix typo
adriendupuis Mar 14, 2025
9634e50
ibexa-user-users.raml: Fix typo
adriendupuis Mar 14, 2025
6f9daa7
REST API: Continue user/users/{userId}/segments responses
adriendupuis Mar 14, 2025
f7fb81d
REST API: Continue user/users/{userId}/segments responses
adriendupuis Mar 17, 2025
430b683
Regenerate REST API Reference's HTML
adriendupuis Mar 17, 2025
bc7f8b8
UserSegmentList.json.example: EOL@EOF
adriendupuis Mar 17, 2025
b82d11e
REST API Ref: Add responses to PATCH /cart/{identifier}
adriendupuis Mar 17, 2025
d9f10b7
REST API Ref: Add responses to POST /cart/{identifier}/entry
adriendupuis Mar 17, 2025
af79700
REST API Ref: Add responses to DELETE /cart/{identifier}/entry/{entryId}
adriendupuis Mar 17, 2025
8dea518
Regenerate REST API Reference's HTML
adriendupuis Mar 17, 2025
a48a365
REST API Ref: Add responses to DELETE /cart/{identifier}/entry/{entryId}
adriendupuis Mar 17, 2025
b1f4c82
REST API Ref: Add responses to PATCH /cart/{identifier}/entry/{entryId}
adriendupuis Mar 17, 2025
c2f3f28
Regenerate REST API Reference's HTML
adriendupuis Mar 17, 2025
1fd7b96
ibexa-types.raml: Fix LocationQuery
adriendupuis Mar 18, 2025
b152461
Regenerate REST API Reference's HTML
adriendupuis Mar 18, 2025
d03fbdc
Merge branch 'master' into complete-rest-api-ref
adriendupuis Apr 25, 2025
394690c
Merge branch 'master' into complete-rest-api-ref
adriendupuis May 15, 2025
27a2fa5
Fix /corporate/companies/{companyId}/members 400 description
adriendupuis May 15, 2025
2214d68
rebuild rest_api_reference.html
adriendupuis May 15, 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
5 changes: 5 additions & 0 deletions ..._reference/input/examples/user/users/user_id/segments/UserSegmentAssignInput.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"UserSegmentAssignInput": {
"segments": ["corporate_account"]
}
}
3 changes: 3 additions & 0 deletions ...i_reference/input/examples/user/users/user_id/segments/UserSegmentAssignInput.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<UserSegmentAssignInput>
<segments>corporate_account</segments>
Copy link
Contributor

Choose a reason for hiding this comment

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

In JSON this part is an array, how to pass multiple segments in XML?

I've tried something like this:

<UserSegmentAssignInput>
    <segments><segment>TestSegment4</segment><segment>TestSegment5</segment></segments>
</UserSegmentAssignInput>

and received:

<?xml version="1.0" encoding="UTF-8"?>
<ErrorMessage media-type="application/vnd.ibexa.api.ErrorMessage+xml">
    <errorCode>406</errorCode>
    <errorMessage>Not Acceptable</errorMessage>
    <errorDescription>Argument 'segments[segment]' is invalid: expected a string</errorDescription>
    <trace>#0 /Users/marek/Desktop/Sites/instance1/vendor/ibexa/rest/src/contracts/Input/ParsingDispatcher.php(111): Ibexa\Bundle\Segmentation\REST\Input\Parser\UserSegmentAssignInput-&gt;parse(Array, Object(Ibexa\Contracts\Rest\Input\ParsingDispatcher))
#1 /Users/marek/Desktop/Sites/instance1/vendor/ibexa/rest/src/contracts/Input/ParsingDispatcher.php(86): Ibexa\Contracts\Rest\Input\ParsingDispatcher-&gt;internalParse(Array, 'application/vnd...')
#2 /Users/marek/Desktop/Sites/instance1/vendor/ibexa/rest/src/lib/Input/Dispatcher.php(115): Ibexa\Contracts\Rest\Input\ParsingDispatcher-&gt;parse(Array, 'application/vnd...'

So maybe it's not possible?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I have no idea.

</UserSegmentAssignInput>
22 changes: 22 additions & 0 deletions ...est_api_reference/input/examples/user/users/user_id/segments/UserSegmentList.json.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
{
"UserSegmentList": {
"_media-type": "application\/vnd.ibexa.api.UserSegmentList+json",
"_href": "\/api\/ibexa\/v2\/user\/users\/14\/segments",
"UserSegment": [
{
"_media-type": "application\/vnd.ibexa.api.UserSegment+json",
"id": 1,
"identifier": "corporate_account",
"name": "Corporate Account",
"SegmentGroup": {
"_media-type": "application\/vnd.ibexa.api.SegmentGroup+json",
"_href": "\/api\/ibexa\/v2\/segment_groups\/corporate_accounts"
},
"User": {
"_media-type": "application\/vnd.ibexa.api.User+json",
"_href": "\/api\/ibexa\/v2\/user\/users\/14"
}
}
]
}
}
10 changes: 10 additions & 0 deletions ...rest_api_reference/input/examples/user/users/user_id/segments/UserSegmentList.xml.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<UserSegmentList media-type="application/vnd.ibexa.api.UserSegmentList+xml" href="/api/ibexa/v2/user/users/14/segments">
<UserSegment media-type="application/vnd.ibexa.api.UserSegment+xml">
<id>1</id>
<identifier>corporate_account</identifier>
<name>Corporate Account</name>
<SegmentGroup media-type="application/vnd.ibexa.api.SegmentGroup+xml" href="/api/ibexa/v2/segment_groups/corporate_accounts"/>
<User media-type="application/vnd.ibexa.api.User+xml" href="/api/ibexa/v2/user/users/14"/>
</UserSegment>
</UserSegmentList>
82 changes: 81 additions & 1 deletion docs/api/rest_api/rest_api_reference/input/ibexa-cart.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ post:
401:
description: Error - the user is not authorized to get this cart.
404:
description: Error - The identifier do not match any Cart.
description: Error - the identifier do not match any cart.
delete:
displayName: Delete Cart
description: Deletes Cart by its identifier.
Expand All @@ -98,11 +98,30 @@ post:
example: |
application/vnd.ibexa.api.CartMetadataUpdate+xml
application/vnd.ibexa.api.CartMetadataUpdate+json
Accept:
description: The updated Cart is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.Cart+xml
application/vnd.ibexa.api.Cart+json
body:
application/vnd.ibexa.api.CartMetadataUpdate+xml:
type: CartMetadataUpdate
application/vnd.ibexa.api.CartMetadataUpdate+json:
type: CartMetadataUpdateWrapper
responses:
200:
description: OK - return the updated cart
body:
application/vnd.ibexa.api.Cart+xml:
type: Cart
application/vnd.ibexa.api.Cart+json:
type: CartWrapper
400:
description: Error - the input doesn't match the input schema definition.
401:
description: Error - the user is not authorized to update this cart.
404:
description: Error - the identifier doesn't match any cart.
/entry:
post:
displayName: Add Entry to Cart
Expand All @@ -113,16 +132,58 @@ post:
example: |
application/vnd.ibexa.api.CartEntryAdd+xml
application/vnd.ibexa.api.CartEntryAdd+json
Accept:
description: The updated Cart is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.Cart+xml
application/vnd.ibexa.api.Cart+json
body:
application/vnd.ibexa.api.CartEntryAdd+xml:
type: CartEntryAdd
application/vnd.ibexa.api.CartEntryAdd+json:
type: CartEntryAddWrapper
example: !include examples/cart/entry/POST/CartEntryAdd.json.example
responses:
200:
description: OK - return the updated cart
body:
application/vnd.ibexa.api.Cart+xml:
type: Cart
application/vnd.ibexa.api.Cart+json:
type: CartWrapper
400:
description: Error - the input doesn't match the input schema definition.
401:
description: Error - the user is not authorized to add an entry to this cart.
404:
description: Error - the identifier doesn't match any cart.
/{entryId}:
delete:
displayName: Remove Entry from Cart
description: Removes the given entry from the given Cart.
headers:
Accept:
description: The updated Cart is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.Cart+xml
application/vnd.ibexa.api.Cart+json
body:
application/vnd.ibexa.api.CartEntryUpdate+xml:
type: CartEntryUpdate
application/vnd.ibexa.api.CartEntryUpdate+json:
type: CartEntryUpdateWrapper
responses:
200:
description: OK - return the updated cart
body:
application/vnd.ibexa.api.Cart+xml:
type: Cart
application/vnd.ibexa.api.Cart+json:
type: CartWrapper
401:
description: Error - the user is not authorized to remove an entry from this cart.
404:
description: Error - the identifiers don't match any cart or entry.
patch:
displayName: Update Entry from Cart
description: Updates the given entry from the given Cart.
Expand All @@ -132,11 +193,30 @@ post:
example: |
application/vnd.ibexa.api.CartEntryUpdate+xml
application/vnd.ibexa.api.CartEntryUpdate+json
Accept:
description: The updated Cart is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.Cart+xml
application/vnd.ibexa.api.Cart+json
body:
application/vnd.ibexa.api.CartEntryUpdate+xml:
type: CartEntryUpdate
application/vnd.ibexa.api.CartEntryUpdate+json:
type: CartEntryUpdateWrapper
responses:
200:
description: OK - return the updated cart
body:
application/vnd.ibexa.api.Cart+xml:
type: Cart
application/vnd.ibexa.api.Cart+json:
type: CartWrapper
400:
description: Error - the input doesn't match the input schema definition.
401:
description: Error - the user is not authorized to update an entry of this cart.
404:
description: Error - the identifiers don't match any cart or entry.
/empty:
post:
displayName: Empty Cart
Expand Down
2 changes: 1 addition & 1 deletion docs/api/rest_api/rest_api_reference/input/ibexa-corporate.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,10 +235,10 @@ get:
type: MemberListWrapper
example: !include examples/corporate/companies/company_id/members/GET/MemberList.json.example
400:
description: Returned when invalid Criterion or Sort clause is used.
body:
application/vnd.ibexa.api.ErrorMessage:
type: ErrorMessage
description: Returned when invalid Criterion or Sort clause is used.
post:
displayName: Create a company member
description: Creates a company member.
Expand Down
42 changes: 40 additions & 2 deletions docs/api/rest_api/rest_api_reference/input/ibexa-types.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1388,7 +1388,7 @@ LocationList:

LocationQuery:
description: 'This class is used to perform a Location query.'
type: object
type: Query

LocationUpdateWrapper:
description: 'JSON object with only a LocationUpdate property.'
Expand Down Expand Up @@ -2305,6 +2305,45 @@ SegmentUpdateWrapper:
properties:
SegmentCreate: SegmentUpdate

UserSegmentList:
description: 'This class lists segment assignements.'
type: object
properties:
UserSegment:
type: UserSegment[]

UserSegmentListWrapper:
description: 'JSON object with only a UserSegmentList property'
type: object
properties:
UserSegmentList: UserSegmentList

UserSegment:
description: 'This class reprensents a segment assigned to a user'
type: object
properties:
id: integer
identifier: string
name: string
SegmentGroup:
type: Ref
User:
type: Ref

UserSegmentAssignInput:
description: 'This class represents a segment assignment input.'
type: object
properties:
segments:
type: array
items: string

UserSegmentAssignInputWrapper:
description: 'JSON object with only a UserSegmentAssignInput property.'
type: object
properties:
UserSegmentAssignInput: UserSegmentAssignInput

SortClause:
description: 'This class is the base for SortClause classes, used to set sorting of content queries.'
type: object
Expand Down Expand Up @@ -6274,4 +6313,3 @@ ActionConfiguration:
updatedAt:
type: datetime
description: 'Timestamp indicating when the action configuration was last updated.'

38 changes: 35 additions & 3 deletions docs/api/rest_api/rest_api_reference/input/ibexa-user-users.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ get:
application/vnd.ibexa.api.UserRefList+json:
type: UserRefListWrapper
404:
description: If there are no visibile Users matching the filter.
description: If there are no visible Users matching the filter.
head:
displayName: Verify Users
description: Verifies if there are Users matching given filter.
Expand All @@ -50,7 +50,7 @@ head:
200:
description: OK - verifies if there are Users matching the given filter.
404:
description: Error - there are no visibile Users matching the filter.
description: Error - there are no visible Users matching the filter.
/current:
get:
displayName: Load current User
Expand Down Expand Up @@ -330,13 +330,24 @@ head:
/segments:
get:
displayName: View user segments
description: TODO
description: Return user's segment list.
headers:
Accept:
description: If set, the user's segment list is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.UserSegmentList+xml
application/vnd.ibexa.api.UserSegmentList+json
responses:
200:
body:
application/vnd.ibexa.api.UserSegmentList+xml:
type: UserSegmentList
example: !include examples/user/users/user_id/segments/UserSegmentList.xml.example
application/vnd.ibexa.api.UserSegmentList+json:
type: UserSegmentListWrapper
example: !include examples/user/users/user_id/segments/UserSegmentList.json.example
404:
description: Error - the user doesn't exist.
post:
displayName: Assign Segments to User
description: Assigns Segments from payload to User given by ID.
Expand All @@ -346,10 +357,31 @@ head:
example: |
application/vnd.ibexa.api.UserSegmentAssignInput+xml
application/vnd.ibexa.api.UserSegmentAssignInput+json
body:
application/vnd.ibexa.api.UserSegmentAssignInput+xml:
type: UserSegmentAssignInput
example: !include examples/user/users/user_id/segments/UserSegmentAssignInput.xml.example
application/vnd.ibexa.api.UserSegmentAssignInput+json:
type: UserSegmentAssignInputWrapper
example: !include examples/user/users/user_id/segments/UserSegmentAssignInput.json.example
responses:
204:
description: No Content - segments assigned to user.
401:
description: Error - the requesting user is not authorized to assign this segment to the given user.
404:
description: Error - the user doesn't exist.
/{segmentIdentifier}:
delete:
displayName: Unassign Segment from User
description: The Segment designated by its identifier is unassigned from the User given by ID.
responses:
204:
description: No Content - segments unassigned from user.
401:
description: Error - the requesting user is not authorized to unassign this segment from the given user.
404:
description: Error - the segment or the user doesn't exist.
/drafts:
get:
displayName: Load user drafts
Expand Down
Loading
Loading