Your First Request
Make your first API call and understand JSON:API responses
Now that you've set up authentication, let's make your first API request to the Wicket MDP API.
Prerequisites
- JWT token generated (see Authentication)
- Your tenant's API URL:
https://tenant-api.wicketcloud.com
Making a Request
Let's fetch a list of people from your Wicket account. This example uses the /people endpoint:
curl -X GET 'https://tenant-api.wicketcloud.com/people?page[size]=5' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/vnd.api+json'const fetch = require('node-fetch');
const apiUrl = 'https://tenant-api.wicketcloud.com';
const token = 'YOUR_JWT_TOKEN';
async function fetchPeople() {
const response = await fetch(`${apiUrl}/people?page[size]=5`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/vnd.api+json'
}
});
const data = await response.json();
console.log(data);
}
fetchPeople();require 'net/http'
require 'json'
api_url = 'https://tenant-api.wicketcloud.com'
token = 'YOUR_JWT_TOKEN'
uri = URI("#{api_url}/people?page[size]=5")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/vnd.api+json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts dataUnderstanding the Response
Wicket's API follows the JSON:API specification. Here's what a successful response looks like:
{
"data": [
{
"id": "8f24a446-acac-40bb-8ff3-e6abc051c362",
"type": "people",
"attributes": {
"uuid": "8f24a446-acac-40bb-8ff3-e6abc051c362",
"given_name": "John",
"family_name": "Smith",
"full_name": "John Smith",
"email": "jsmith@email.ca",
"job_title": "Front End Developer",
"created_at": "2017-07-27T22:21:26.824Z",
"updated_at": "2017-07-27T22:47:45.129Z"
},
"relationships": {
"emails": {
"data": [
{ "id": "abc123", "type": "emails" }
]
},
"phones": {
"data": [
{ "id": "def456", "type": "phones" }
]
}
}
}
],
"links": {
"self": "https://tenant-api.wicketcloud.com/people?page[number]=1&page[size]=5",
"first": "https://tenant-api.wicketcloud.com/people?page[number]=1&page[size]=5",
"next": "https://tenant-api.wicketcloud.com/people?page[number]=2&page[size]=5",
"last": "https://tenant-api.wicketcloud.com/people?page[number]=10&page[size]=5"
},
"meta": {
"total": 47
}
}Response Structure
The JSON:API response includes:
-
data: Array of resource objects (or a single object for individual resources)id: Unique identifier (UUID)type: Resource type (e.g., "people", "organizations")attributes: Resource properties (given_name, email, etc.)relationships: Related resources with identifiers
-
links: Pagination and navigation linksself: Current request URLfirst,next,prev,last: Pagination navigation
-
meta: Additional metadata (e.g., total count) -
included(optional): Full representations of related resources
Fetching a Single Person
You can fetch a specific person by their UUID:
curl -X GET 'https://tenant-api.wicketcloud.com/people/8f24a446-acac-40bb-8ff3-e6abc051c362' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/vnd.api+json'The response will have a single object in data instead of an array:
{
"data": {
"id": "8f24a446-acac-40bb-8ff3-e6abc051c362",
"type": "people",
"attributes": { ... }
}
}Including Related Resources
Use the include parameter to fetch related resources in a single request:
curl -X GET 'https://tenant-api.wicketcloud.com/people/8f24a446-acac-40bb-8ff3-e6abc051c362?include=emails,phones,addresses' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/vnd.api+json'Related resources appear in the included array:
{
"data": { ... },
"included": [
{
"id": "abc123",
"type": "emails",
"attributes": {
"email_address": "jsmith@email.ca",
"email_type": "work"
}
},
{
"id": "def456",
"type": "phones",
"attributes": {
"phone_number": "+1-555-123-4567",
"phone_type": "mobile"
}
}
]
}Common Response Codes
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | Successful request |
| 201 | Created | Resource created successfully |
| 204 | No Content | Successful deletion |
| 400 | Bad Request | Invalid request format |
| 401 | Unauthorized | Missing or invalid JWT token |
| 404 | Not Found | Resource doesn't exist |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
Error Responses
Errors also follow JSON:API format:
{
"errors": [
{
"status": "404",
"code": "record_not_found",
"title": "Record Not Found",
"detail": "Couldn't find Person with 'id'=invalid-uuid"
}
]
}Each error object includes:
status: HTTP status codecode: Machine-readable error codetitle: Human-readable summarydetail: Detailed error message
Parsing Responses
Here's how to extract data from a JSON:API response:
// Fetch people and extract names
const response = await fetch(`${apiUrl}/people?page[size]=5`, {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/vnd.api+json'
}
});
const json = await response.json();
// Extract person names
const people = json.data.map(person => ({
id: person.id,
name: person.attributes.full_name,
email: person.attributes.email
}));
console.log(people);
// [{ id: '...', name: 'John Smith', email: 'jsmith@email.ca' }, ...]# Fetch people and extract names
uri = URI("#{api_url}/people?page[size]=5")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/vnd.api+json'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
# Extract person names
people = data['data'].map do |person|
{
id: person['id'],
name: person['attributes']['full_name'],
email: person['attributes']['email']
}
end
puts people
# [{:id=>"...", :name=>"John Smith", :email=>"jsmith@email.ca"}, ...]