Set of tools to parse/format or serialize/deserialize data for JSON API Specification
npm install n8n-nodes-json-api-specThis is an n8n community node. It lets you serialize data to JSON API Specification format in your n8n workflows.
JSON API is a specification for building APIs in JSON. This node helps you transform your data into JSON API compliant format with proper structure including resource type, id, and attributes.
n8n is a fair-code licensed workflow automation platform.
Installation
Operations
Compatibility
Usage
Resources
TODO
Follow the installation guide in the n8n community nodes documentation.
The JSON API Serializer node supports the following operations:
data object containing:id - The resource identifiertype - The resource typeattributes - The resource attributes as a JSON objectdata array, where each item contains:id - The resource identifiertype - The resource typeattributes - The resource attributes as a JSON objectdata.relationships and included keys with the resources provided.include query parameter pattern.- Include Filter: A comma-separated list of relationship names to include (e.g., sector,owner)
- If empty, no relationships or included resources will be returned
- The filter matches against the relationship name (or type if no custom name is set)
- Default value pulls from $('Webhook').first().json.query.include to automatically use the include parameter from incoming API requests
links and meta sections:links - Contains first, prev, next, last URLs for navigationmeta - Contains page info (current, size, total) and total resource count- Tested against: n8n 1.113.3
Input parameters:
- Response: Resource Object
- Type: organization
- ID: 42
- Attributes: {"name": "Agile Freaks SRL", "country": "Romania", "region": "Sibiu"}
Output:
``json`
{
"data": {
"id": "42",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "Romania",
"region": "Sibiu"
}
}
}
Input parameters:
- Response: Resources Array
- Configure the Type, ID, and Attributes for each input item
Output:
`json`
{
"data": [
{
"id": "1",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "USA"
}
},
{
"id": "2",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "Germany"
}
}
]
}
Input parameters:
- Response: Resource Objectorganization
- Type: 6937
- ID: {"name": "Test organization", "country": "Kenya", "region": "africa"}
- Attributes: true
- Enable Include Relationships: {{ $('Webhook').first().json.query.include }}
- Include Filter: (default)sector
- Include Resources:
- Resource:
- Type: {"id": "1", "name": "Technology"}
- Attributes:
Output:
`json`
{
"data": {
"id": "6937",
"type": "organization",
"attributes": {
"name": "Test organization",
"country": "Kenya",
"region": "africa"
},
"relationships": {
"sector": {
"id": "1",
"type": "sector"
}
}
},
"included": [
{
"id": "1",
"type": "sector",
"attributes": {
"name": "Technology"
}
}
]
}
This example shows how to filter which relationships are returned. When you have multiple relationships configured but only want to return specific ones based on the API request.
Input parameters:
- Response: Resource Objectorganization
- Type: 42
- ID: {"name": "Agile Freaks SRL", "country": "Romania"}
- Attributes: true
- Enable Include Relationships: sector
- Include Filter: (only return sector, not owner)sector
- Include Resources:
- Resource:
- Type: sector
- Relationship Name: {"id": "1", "name": "Technology"}
- Attributes: owner
- Resource:
- Type: owner
- Relationship Name: {"id": "1", "name": "Boss"}
- Attributes:
Output:
`json`
{
"data": {
"id": "42",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "Romania"
},
"relationships": {
"sector": {
"data": {
"id": "1",
"type": "sector"
}
}
}
},
"included": [
{
"id": "1",
"type": "sector",
"attributes": {
"name": "Technology"
}
}
]
}
Note that even though both sector and owner are configured as Include Resources, only sector appears in the output because the Include Filter is set to sector. This allows you to configure all possible relationships once and dynamically filter them based on the incoming API request's include parameter.
Input parameters:
- Response: Resource Objectorganization
- Type: 42
- ID: {"name": "Agile Freaks SRL", "country": "Romania", "region": "Sibiu"}
- Attributes: true
- Enable Include Relationships: {{ $('Webhook').first().json.query.include }}
- Include Filter: (default)sector
- Include Resources:
- Resource:
- Type: {"id": "1", "name": "Technology"}
- Attributes: owner
- Resource:
- Type: {"id": "1", "name": "Boss"}
- Attributes:
Output:
`json`
{
"data": {
"id": "42",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "Romania",
"region": "Sibiu"
},
"relationships": {
"sector": {
"id": "1",
"type": "sector"
},
"owner": {
"id": "1",
"type": "owner"
}
}
},
"included": [
{
"id": "1",
"type": "sector",
"attributes": {
"name": "Technology"
}
},
{
"id": "1",
"type": "owner",
"attributes": {
"name": "Boss"
}
}
]
}
You can specify a custom name for relationships that differs from the resource type. This is useful when the semantic meaning of the relationship differs from the resource type itself.
Input parameters:
- Response: Resource Objectcontact
- Type: 42
- ID: {"name": "Mister Daniel"}
- Attributes: true
- Enable Include Relationships: {{ $('Webhook').first().json.query.include }}
- Include Filter: (default)organization
- Include Resources:
- Resource:
- Type: membership
- Relationship Name: {"id": "42", "name": "Agile Freaks SRL", "country": "Romania", "region": "Sibiu"}
- Attributes:
Output:
`json`
{
"data": {
"id": "42",
"type": "contact",
"attributes": {
"name": "Mister Daniel"
},
"relationships": {
"membership": {
"data": {
"id": "42",
"type": "organization"
}
}
}
},
"included": [
{
"id": "42",
"type": "organization",
"attributes": {
"name": "Agile Freaks SRL",
"country": "Romania",
"region": "Sibiu"
}
}
]
}
In this example, even though the resource type is organization, the relationship is named membership to better represent the semantic relationship between a contact and their organization.
Input parameters:
- Response: Resources Arraycontact
- Type: enabled
- Add Pagination: http://localhost:5678/webhook/v1/contacts
- Base URL: 2
- Current Page: 200
- Items Per Page: 800
- Total Resource Count: {"filter": {"organization_id": "42"}, "sort": "name"}
- Query Params:
Output:
`json`
{
"data": [
{
"id": "1",
"type": "contact",
"attributes": {
"name": "John Doe"
}
},
{
"id": "2",
"type": "contact",
"attributes": {
"name": "Jane Smith"
}
}
],
"links": {
"first": "http://localhost:5678/webhook/v1/contacts?filter%5Borganization_id%5D=42&sort=name&page=1&per_page=200",
"prev": "http://localhost:5678/webhook/v1/contacts?filter%5Borganization_id%5D=42&sort=name&page=1&per_page=200",
"next": "http://localhost:5678/webhook/v1/contacts?filter%5Borganization_id%5D=42&sort=name&page=3&per_page=200",
"last": "http://localhost:5678/webhook/v1/contacts?filter%5Borganization_id%5D=42&sort=name&page=4&per_page=200"
},
"meta": {
"page": {
"current": 2,
"size": 200,
"total": 4
},
"total_contact_count": 800
}
}
Pagination Notes:
- prev is null on the first pagenext
- is null on the last pagetotal_
- The key is dynamically named based on the resource type$('Webhook').first().json.query
- Query Params accepts a JSON object (e.g., from ) and preserves all params except page and per_pagefilter[organization_id]
- Nested objects like are properly serialized
and included sections
- Each included resource requires a Type
- The Relationship Name is required and specifies the key name for the relationship in the output
- The Attributes must be a JSON object that includes an id field - this id will be extracted and used for the relationship reference
- Use the Resource Object response type when you need to serialize a single item
- Use the Resources Array response type when working with multiple items from previous nodes
- The node follows the JSON API v1.0 specificationResources
* n8n community nodes documentation
* JSON API Specification
* JSON API Format Documentation
Development Setup
1. Clone this repository.
2. Install node and npm. https://nodejs.org/en/download
3. Install pnpm
`bash
npm i -g pnpm
`
4. Install local package
`bash
pnpm install
`
5. Build n8n
`bash
pnpm run build
`
6. Run n8n in docker mode
7. Configure n8n docker container to use this custom node. Add the following volume for n8n-main service. You have to determine YOUR_PATH by running pwd in the location you cloned this repo at. Can look something like /Users/.../n8n-nodes-json-api-spec.
`yaml
volumes:
- {YOUR_PATH}/dist:/home/node/.n8n/custom/node_modules/n8n-nodes-json-api-spec
`Development
1. Make changes to nodes or credentials
2. Delete compiled files
`bash
rm -rf dist
`
3. Build packages and n8n
`bash
pnpm run build
`
4. Restart n8n (make sure to be in n8n directory)
`bash
docker compose restart n8n-main
`Publishing Package on npm
1. Update version (patch / minor / major)
`bash
npm version patch
`2. Push version update on git
`bash
git push
`3. Publish version on npm
`bash
npm publish
``- [ ] Support relationships and included resources for array responses