When working with REST APIs, especially in a system as robust as FlexVertex, it is crucial to understand the difference between parameters and payloads. Both are key components in API requests but serve different purposes. The FlexVertex REST API uses parameters and payloads to manage the interaction between the client and the server, but each has specific use cases and implications. Let’s explore these two concepts and how they fit into the FlexVertex architecture.
Parameters in a REST API request are generally used to filter, identify, or narrow down data during retrieval operations. These can be sent via the URL as query parameters.
Query Parameters: Query parameters allow for flexible filtering and sorting of data. They are appended to the endpoint URL and used primarily for data retrieval operations, such as listing objects that match certain criteria. In FlexVertex, you might use query parameters to filter based on object properties:
GET /rest/schema/sql?query=select * from Person where InfluencerRating >95&dns=/Your-domain/Your-nexus/Your-schema
In this example, the query contains a SQL statement to retrieve certain objects.
GET /rest/schema/loadObject?objectKey=FgEAFgEBFgECFkABMOBq9WoXoEvZuL-6oIdxOw0=
This GET request loads an object based on its unique identifier.
Query parameters are primarily used for GET requests, where the client seeks to retrieve data without sending a body or payload. They are typically lightweight and concise, often representing specific filtering or identifying criteria.
Payloads, on the other hand, are the actual body of the request and are typically used in POST requests. They are used when the client needs to send data to the server to either create a new resource or update an existing one. In FlexVertex, payloads play a significant role when working with objects and relationships, as they allow clients to send complex structures that the system needs to process.
For instance, when creating a new object in FlexVertex, a payload is sent with all the relevant properties that define that object:
POST /rest/schema/createObject
Content-Type: application/json
{
"class": "Destination",
"properties": {"Location": "Denali", "Type": "Mountain"},
"dns": "/Your-domain/Your-nexus/Your-schema"
}
In this case, the properties portion of the payload contains two fields—Location and Type—that define the new object (of class Destination). FlexVertex processes this data to create the object in the system.
The FlexVertex REST API is capable of creating multiple types of objects in the same payload:
POST /rest/schema/createObjects
Content-Type: application/json
{
"objects": [
{"class": "Person", "properties": {"Name": "Roberto", "Income": "99999"}},
{"class": "Interest", "properties": {"Type": "Golf"}},
{"class": "Person", "properties": {"Name": "Lalo", "Income": "83711"}},
{"class": "Interest", "properties": {"Type": "Gardening"}}
],
"dns": "/Your-domain/Your-nexus/Your-schema"
}
For this example, objects of class Person and Interest are being created from a single payload.
Payloads may also be used to transmit direct SQL for creating new objects:
POST /rest/schema/sql
Content-Type: application/json
{
"query": "insert into Destination (Location, Type) values ('Hawaii', 'Tropical')",
"dns": "/Your-domain/Your-nexus/Your-schema"
}
Payloads allow for more complex and detailed data transactions compared to parameters. For instance, while a query parameter might tell the system to return a list of products, a payload can define the specific details of a new product to be added to the system.
In FlexVertex, understanding when to use parameters versus payloads is essential for efficient API interaction. Parameters are ideal for simple filtering and identification in GET requests, while payloads handle more complex data operations when creating or modifying resources. Mastering both ensures that you can harness the full power of the FlexVertex REST API.