How to send a request in Data Exchange API
Edit on GitHubThis guide shows how to send a request in Data Exchange API.
Ensure the Data Exchange API is integrated (follow Data Exchange API integration) and configured (follow How to configure Data Exchange API) as described in the guides.
Let’s say you have an endpoint /dynamic-data/country
to operate with data in spy_country
table in database.
The Data Exchange API is a non-resource-based API and routes directly to a controller all specified endpoints.
By default, all routes within the Data Exchange API are protected to ensure data security.
To access the API, you need to obtain an access token by sending a POST request to the /token/
endpoint with the appropriate credentials:
POST /token/ HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Content-Length: 67
grant_type=password&username={username}&password={password}
Sending a GET
request
To retrieve a collection of countries, a GET
request should be sent to the /dynamic-entity/country
endpoint.
This request needs to include the necessary headers, such as Content-Type, Accept, and Authorization, with the access token provided.
The response body will contain all the columns from the spy_country
table that have been configured in the spy_dynamic_entity_definition.definition
.
Each column will be represented using the fieldVisibleName
as the key, providing a comprehensive view of the table’s data in the API response.
Pagination allows for efficient data retrieval by specifying the desired range of results. To implement pagination, include the desired page limit and offset in the request:
GET /dynamic-entity/country?page[offset]=1&page[limit]=2 HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
If everything is set up correctly you will get the following response:
[
{
"id_country": 2,
"iso2_code": "AD",
"iso3_code": "AND",
"name": "Andorra",
"postal_code_mandatory": true,
"postal_code_regex": "AD\\d{3}"
},
{
"id_country": 3,
"iso2_code": "AE",
"iso3_code": "ARE",
"name": "United Arab Emirates",
"postal_code_mandatory": false,
"postal_code_regex": null
}
]
Note, by default the API GET
request returns up to 20 records.
Filtering enables targeted data retrieval, refining the response to match the specified criteria. To apply filtering to the results based on specific fields, include the appropriate filter parameter in the request:
GET /dynamic-entity/country?filter[country.iso2_code]=AA HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
If everything is set up correctly you will get the following response:
[
{
"id_country": 1,
"iso2_code": "AA",
"iso3_code": "UUD",
"name": "Create",
"postal_code_mandatory": false,
"postal_code_regex": null
}
]
Note, so far when you combine multiple filters in a single request, the system applies an “AND” condition to the retrieved results.
To retrieve a country by a specific ID, you can send a GET
request with the following parameters:
GET /dynamic-entity/country/3 HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
If everything is set up correctly you will get the following response:
[
{
"id_country": 3,
"iso2_code": "AE",
"iso3_code": "ARE",
"name": "United Arab Emirates",
"postal_code_mandatory": false,
"postal_code_regex": null
}
]
Note if a current endpoint is not configured in spy_dynamic_entity_configuration
and it’s not found you’ll get the following response:
[
{
"message": "Not found",
"status": 404,
"code": "007"
}
]
Sending POST
request
To create a collection of countries, submit the following HTTP request:
POST /dynamic-entity/country HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
Content-Length: 154
{
"data": [
{
"iso2_code": "WA",
"iso3_code": "WWA",
"name": "FOO"
}
]
}
If everything is set up correctly you will get the following response:
[
{
"iso2_code": "WA",
"iso3_code": "WWA",
"name": "FOO",
"id_country": 257
}
]
The response payload includes all the specified fields from the request body, along with the ID of the newly created entity.
Note that all fields included in the request payload are marked as isCreatable: true
in the configuration.
Therefore, the API will create a new record with all the provided fields.
However, if any of the provided fields are configured as isCreatable: false
it will result in an error.
Let’s configure isCreatable: false
for iso3_code
and send the same request.
You will receive the following error response because a non-creatable field iso3_code
is provided:
[
{
"message": "Modification of immutable field `iso3_code` is prohibited.",
"status": 400,
"code": "1304"
}
]
It is important to consider that certain database-specific configurations may result in issues independent of entity configurations.
For instance, in the case of MariaDB, it is not possible to set the ID value for an auto-incremented field.
Additionally, for the iso2_code
field in the spy_country
table, it must have a unique value.
Therefore, before creating a new record, it is necessary to verify that you do not pass a duplicated value for this field.
Otherwise, you will receive the following response:
[
{
"message": "Failed to persist the data. Please verify the provided data and try again. Entry is duplicated.",
"status": 400,
"code": "1309"
}
]
This response is caused by a caught Propel exception, specifically an integrity constraint violation (Integrity constraint violation: 1062 Duplicate entry 'WA' for key 'spy_country-iso2_code')
.
Sending PATCH
request
To update a collection of countries, submit the following HTTP request:
PATCH /dynamic-entity/country HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
Content-Length: 174
{
"data": [
{
"id_country": 1,
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO"
}
]
}
If everything is set up correctly you will get the following response:
[
{
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO",
"id_country": 1
}
]
The response payload includes all the specified fields from the request body.
It is also possible to send a PATCH
request for a specific ID instead of a collection, use the following request:
PATCH /dynamic-entity/country/1 HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
Content-Length: 143
{
"data": {
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO"
}
}
Note that all fields included in the request payload are marked as isEditable: true
in the configuration.
Therefore, the API will update the found record with all the provided fields.
However, if any of the provided fields are configured as isEditable: false
it will result in an error.
Let’s configure isEditable: false
for iso3_code
and send the same request.
You will receive the following error response because a non-editable field iso3_code
is provided:
[
{
"message": "Modification of immutable field `iso3_code` is prohibited.",
"status": 400,
"code": "1304"
}
]
If id_country
is not provided you will get the following response:
[
{
"message": "Incomplete Request - missing identifier.",
"status": 400,
"code": "1310"
}
]
If id_country
is not found you will get the following response:
[
{
"message": "The entity could not be found in the database.",
"status": 404,
"code": "1303"
}
]
Similarly to the POST
request, it is important to consider database-specific configurations when sending a PATCH
request.
Sending PUT
request
When you send a PUT request, you provide the updated representation of the resource in the request payload. The server then replaces the entire existing resource with the new representation provided. If the resource does not exist at the specified URL, a PUT request can also create a new resource.
Let’s send the following PUT
request to update the existing entity:
PUT /dynamic-entity/country HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
Content-Length: 263
{
"data": [
{
"id_country": 1,
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO"
}
]
}
If everything is set up correctly you will get the following response:
[
{
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO",
"postal_code_mandatory": null,
"postal_code_regex": null,
"id_country": 1
}
]
The response payload includes all touched fields for the provided resource.
It is also possible to send a PUT
request for a specific ID instead of a collection using the following request:
PUT /dynamic-entity/country/1 HTTP/1.1
Host: glue-backend.mysprykershop.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {your_token}
Content-Length: 143
{
"data": {
"iso2_code": "WB",
"iso3_code": "WWB",
"name": "FOO"
}
}
When using PUT
requests, it’s important to consider that the same rules and configurations apply
as with PATCH
and POST
requests. This means that the isEditable
attribute determines whether existing
items can be modified during a PUT
request. Additionally, the isCreatable
attribute is used for non-existing
items that are created automatically according to the PUT
request RFC.
In technical terms, the PUT
request follows the same guidelines as PATCH
and POST
requests in relation to
the definition and database-specific configurations. The isEditable
attribute governs the update capability
of existing items during a PUT
request, ensuring that only editable fields can be modified. Similarly, the isCreatable
attribute pertains to non-existing items and governs their automatic creation as part of the PUT
request process,
adhering to the standards outlined in the PUT
request RFC. It’s crucial to adhere to these rules and configurations
to ensure accurate and consistent data manipulation during PUT
operations.
Error codes
Bellow you can find a list of error codes that you can receive when sending GET
, POST
, PATCH
or PUT
requests.
Error code | Message | Description |
---|---|---|
1301 | Invalid or missing data format. Please ensure that the data is provided in the correct format. Example request body: {'data':[{...},{...},..]} |
The request body is not valid. Please review the data format for validity. Ensure that the data is provided in the correct format. An example request body would be: {'data':[{...data entity...},{...data entity...},...]} . data If the data format is invalid or missing, an error message will be displayed. |
1302 | Failed to persist the data. Please verify the provided data and try again. | The data could not be persisted in the database. Please verify the provided data entities and try again. |
1303 | The entity could not be found in the database. | The requested entity could not be found in the database for retrieval or update. |
1304 | Modification of immutable field field is prohibited. |
The field is prohibited from being modified. Please check the configuration for this field. |
1305 | Invalid data type for field: field |
The specified field has an incorrect type. Please check the configuration for this field and correct the value. |
1306 | Invalid data value for field: field , row number: row . Field rules: validation rules . |
The error indicates a data row and a field that does not comply with the validation rules in the configuration. Here is an example of the error: Invalid data value for field: id, row number: 2. Field rules: min: 0, max: 127 . |
1307 | The required field must not be empty. Field: field |
The specified field is required according to the configuration. The field was not provided. Please check the data you are sending and try again. |
1308 | Entity not found by identifier, and new identifier can not be persisted. Please update the request. | The entity could not be found using the provided identifier, and a new identifier cannot be persisted. Please update your request accordingly or check configuration for identifier field. |
1309 | Failed to persist the data. Please verify the provided data and try again. Entry is duplicated. | Failed to persist the data. Please verify the provided data and try again. This error may occur if a record with the same information already exists in the database. |
1310 | Incomplete Request - missing identifier. | The request is incomplete. The identifier is missing. Please check the request and try again. |
Thank you!
For submitting the form