Api Design / QA Plan

API OVERVIEW

A.R.B.O.L (Relational Grouping Based on Logical Order) is a RESTful API designed to classify and manage nodes organized within a hierarchical category structure, and filterable through one or more tags. The API provides full CRUD (Create, Read, Update, Delete) operations for each core resource — Nodes, Tags, and Categories — allowing flexible data manipulation and retrieval.

Usage

This API is suitable for applications that require complex data organization, such as dashboards, catalogs, or inventory systems. No authentication is required at this stage.

This API is under active development and subject to change. Future versions may include expanded query capabilities and user management features.

Resources

The current version of the API supports the following core resources:

Category – hierarchical containers for grouping nodes
Tag – keywords for flexible filtering and classification
Node – individual entities identified by customizable attributes

Response Format

All API endpoints return structured JSON responses in a consistent format to simplify client-side handling and error processing.

Success Responses

Depending on the action, successful responses return either a single object or a list of object, wrapped under a key matching the resource name:

Single Resource (show, create, update)

{
  "node": {
    "id": 1,
    "name": "FirstNode",
    "plate": "ABC123",
    ...
  }
}

{
  "tag": {
    "id": 5,
    "name": "#alert"
  }
}

{
  "category": {
    "id": 3,
    "name": "Main Category",
    "parent_id": null
  }
}

Multiple Resources (index)

{
  "nodes": [
    {
      "id": 1,
      "name": "FirstNode",
      ...
    },
    {
      "id": 2,
      "name": "SecondNode",
      ...
    }
  ]
}

{
  "tags": [
    { "id": 1, "name": "#green" },
    { "id": 2, "name": "#alert" }
  ]
}

{
  "categories": [
    { "id": 1, "name": "Root", "parent_id": null },
    { "id": 2, "name": "Subcategory", "parent_id": 1 }
  ]
}

Error Responses Custom validation errors:

Field	Message	Condition
`seal`	"Only 3 uppercase letters are allowed"	Must be exactly 3 uppercase A–Z characters
`serie`	"Only 3 digits are allowed"	Must be exactly 3 digits (e.g., "123")
`plate`	"Invalid plate format"	Must follow the pattern: 3 uppercase letters + 3 digits (e.g., "ABC123")
`code_version`	"must be 1, 3, 4, or 5"	Must be one of the allowed UUID versions
`code_url`	"must be present for UUID versions 3 and 5"	Required if `code_version` is 3 or 5

JSON Serialization

This API uses the Blueprinter serialization library to ensure consistent and standardized JSON responses across all endpoints. Each resource is exposed through a blueprint that defines the structure of the output, allowing clients to consume predictable and clean data formats.

API CORE RESOURCES

Node

A Node represents a primary data entity identified by both an id and a UUID (reference_code), both serving as unique identifiers. Each node contains a combination of required and optional attributes, including physical properties (size, number), identification codes (plate, seal, serie), and classification details (status, time_slot).

Nodes are always associated with a Category (category_id) and can be linked to one or more Tags to support flexible filtering and classification. Several fields follow strict formatting rules — for example, serie must consist of exactly 3 digits, and seal must be 3 uppercase letters. Some attributes are computed automatically based on internal logic and virtual parameters:

reference_code is derived from the virtual attributes code_version and code_url, ensuring a consistent UUID format.
plate is generated by combining seal and serie.
time_slot and relative_age are calculated based on the created_at timestamp.

The model also includes custom logic for validations, as well as enumerated types for status and time_slot. These computed fields ensure consistency and reduce manual errors in data entry while enabling rich querying and organization capabilities.

Node blueprint output

{
  "id": 1,
  "name": "NewNode",
  "description": null,
  "number": 4,
  "plate": "ABC123",
  "reference_code": "ab7e7f90-14cd-42fb-8d25-bc5dcae5f9c0",
  "relative_age": 6,
  "seal": "ABC",
  "serie": "123",
  "size": 30,
  "status": "active",
  "time_slot": "morning",
  "category_id": 1,
  "category": {"id": 1, "name": "NewCategory"},
  "created_at": "2025-06-14T10:34:56Z"
}

List Nodes

`GET /nodes`

Retrieves a list of all nodes. Note: Pagination and query parameters are not yet supported in this version

Response

Returns an array of Node objects, each serialized according to the blueprint format described previously.

Status: 200 OK

[
  {
    "id": 1,
    "name": "FirstNode",
    ...
  },
  {
    "id": 2,
    "name": "SecondNode",
    ...
  }
]

Create Node

`POST /nodes`

Request Body

"node": {
  "name": "NewNode",
  "number": 4,
  "seal": "ABC",
  "serie": "123",
  "size": 30,
  "status": "active",
  "category_id": category.id,
  "code_version": 1
}

Required Fields

name (string): Must be present and unique.
number (integer): Required. Must be an integer value.
seal (string, 3 uppercase letters): Required. Must match the format /^[A-Z]{3}$/. Used to build the plate.
serie (string, 3 digits): Required. Must match the format /^\d{3}$/. Used to build the plate.
size (float): Required. Must be a number between 22 and 36 inclusive.
status (string): Required. Used to indicate state (Active, Inactive, Deprecated).
category_id (integer): Must refer to an existing category.
code_version (string): Virtual attribute used to compute the reference_code.

Optional fields:

description (text): Optional textual description of the node.
code_url (string): Used to compute the reference_code. Required if code_version is either 3 or 5.

Auto-computed Fields These are not required in the request body but will be included in the response:

plate (string): Auto-generated by combining seal and serie****.
reference_code (UUID): Generated using code_version and code_url****.
time_slot (string): Derived from created_at ("morning", "afternoon", "night").
relative_age (integer): Calculated based on created_at and the time_slot attribute.

Response Returns all attributes of the created node. Structure matches the blueprint format described previously.

Status: 201 Created

{ 
  "id": 3,
  "name": "NewNode",
  "description": null,
  "number": 4,
  "plate": "ABC123",
  "reference_code": "ab7e7f90-14cd-42fb-8d25-bc5dcae5f9c0",
  "relative_age": 6,
  "seal": "ABC",
  "serie": "123",
  "size": 30,
  "status": "active",
  "time_slot": "morning",
  "category_id": 1,
  "category": {"id": 1, "name": "NewCategory"},
  "created_at": "2025-06-14T10:34:56Z"
}

Errors

400 Bad Request: Missing parameters.

{
    "errors": [
        "param is missing or the value is empty: node"
    ]
}

422 Unprocessable Entity: Invalid parameters. Example:

{
    "errors": [
        <Validation message>
    ]
}

Show Node

`GET /nodes/:id`

Retrieves details of a single node by its ID.

Response

Returns the blueprint extended format described previously for the requested category.

Status: 200 OK

{ 
  "id": 3,
  "name": "NewNode",
  "description": null,
  "number": 4,
  "plate": "ABC123",
  "reference_code": "ab7e7f90-14cd-42fb-8d25-bc5dcae5f9c0",
  "relative_age": 6,
  "seal": "ABC",
  "serie": "123",
  "size": 30,
  "status": "active",
  "time_slot": "morning",
  "category_id": 1,
  "category": {"id": 1, "name": "NewCategory"},
  "created_at": "2025-06-14T10:34:56Z"
}

Errors

404 Not Found: The specified id does not correspond to any existing category

{
    "errors": [
        "Couldn't find Node with 'id'=99"
    ]
}

Update Node

`PATCH /nodes/:id`

Request Body

{
  "node": {
    "name": "UpdatedNode",
    "description": "New description"
  }
}

Response Returns all attributes of the updated node. Structure matches the blueprint format described previously.

Status: 200 OK

{ 
  "id": 3,
  "name": "UpdatedNode",
  "description": "New description",
  "number": 4,
  "plate": "ABC123",
  "reference_code": "ab7e7f90-14cd-42fb-8d25-bc5dcae5f9c0",
  "relative_age": 6,
  "seal": "ABC",
  "serie": "123",
  "size": 30,
  "status": "active",
  "time_slot": "morning",
  "category_id": 1,
  "category": {"id": 1, "name": "NewCategory"},
  "created_at": "2025-06-14T10:34:56Z"
}

Errors 422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

`PUT /nodes/:id`

Request Body All required attributes must be provided. Any fields not included will be removed or set to null, if allowed by the model. This endpoint fully replaces the existing Node resource

{
  "node": {
    "name": "OtherUpdatedNode",
    "description": "Otherdescription",
    "number": 2,
    "seal": "XYZ",
    "serie": "789",
    "size": 28,
    "status": "active",
    "category_id": category.id,
    "code_version": 4
  }
}

Response Returns all attributes of the updated node. Structure matches the blueprint format described previously.

Status: 200 OK

{ 
  "id": 4,
  "name": "OtherUpdatedNode",
  "description": "Other description",
  "number": 2,
  "plate": "XYZ789",
  "reference_code": "ab7e7f90-14cd-42fb-8d25-bc5dcae5f9c0",
  "relative_age": 6,
  "seal": "XYZ",
  "serie": "789",
  "size": 28,
  "status": "active",
  "time_slot": "morning",
  "category_id": 1,
  "category": {"id": 1, "name": "NewCategory"},
  "created_at": "2025-06-14T10:34:56Z",
  "updated_at": "2025-07-24T10:40:51Z"
}

Errors 422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

Delete Node

`DELETE /nodes/:id`

Deletes the node with the specified ID from the system.

Response

Status: 204 No Content Indicates that the node was successfully deleted. The response body is intentionally empty.

Errors

404 Not Found. The specified id does not correspond to any existing node.

 {
    "errors": [
        "Couldn't find Node with 'id'=99"
    ]
}

Category

Categories are organized in a hierarchical structure using a self-referential model. Each category can have a parent category or act as a root, enabling the creation of nested classification trees. A node belongs to a single category, allowing for consistent and logical grouping within the system. This resource supports flexible serialization through custom blueprint views:

The default view shows the id, name and parent_id attirbutes
The basic view returns minimal data (id and name).
The extended view includes the parent category's basic details, allowing for richer hierarchical context when needed.

Category blueprint outputs

Default:

{
  "id": 1,
  "name": "NewCategory",
  "parent_id": null,
}

Basic:

{
  "id": 1,
  "name": "NewCategory"
}

Extended:

{
  "id": 2,
  "name": "ChildCategory",
  "parent": {"id": 1, "name": "NewCategory"},
}

List Categories

`GET /categories`

Retrieves a list of all categories. Note: Pagination and query parameters are not yet supported in this version

Response

Returns an array of Category objects, each serialized according to the default view blueprint format described previously.

Status: 200 OK

[
  {
    "id": 1,
    "name": "NewCategory",
    "parent_id": null,
  },
  {
    "id": 2,
    "name": "SecondCategory",
    "parent_id": 1,
  }
]

Create Category

`POST /categories`

Request Body

"category": {
  "name": "OtherCategory",
  "parent_id": 1
}

Required Fields

name (string): Must be present and unique.

Optional fields:

parent_id (integer): References another category to establish a hierarchical relationship. If provided, this category will be considered a child of the specified parent.

Response

Returns the blueprint with the ‘default’ view format described previously for the created category.

Status: 201 Created

{
    "id": 2,
    "name": "OtherCategory",
    "parent_id": 1,
}

Errors

400 Bad Request: Missing parameters.

{
    "errors": [
        "param is missing or the value is empty: category"
    ]
}

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

Show Category

`GET /categories/:id`

Retrieves details of a single category by its ID.

Response

Returns the blueprint extended format described previously for the requested category.

Status: 200 OK

{
  "id": 3,
  "name": "ThirdCategory",
  "parent": {"id": 1, "name": "NewCategory"},
}

Errors

404 Not Found: The specified id does not correspond to any existing category

{
    "errors": [
        "Couldn't find Category with 'id'=99"
    ]
}

Update Category

`PATCH /categories/:id`

Request Body

"category": {
  "name": "UpdatedCategory"
}

Response

Returns the blueprint extended format described previously for the updated category.

Status: 200 OK

{
  "id": 3,
  "name": "UpdatedCategory",
  "parent": {"id": 1, "name": "NewCategory"},
}

Errors

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

`PUT /categories/:id`

Request Body

All required attributes must be provided. Any fields not included will be removed or set to null, if allowed by the model. This endpoint fully replaces the existing Category resource

"category": {
  "name": "OtherUpdatedCategory",
  "parent_id": 1
}

Response

Returns the blueprint extended format described previously for the updated category.

Status: 200 OK

{
  "id": 3,
  "name": "OtherUpdatedCategory",
  "parent": {"id": 1, "name": "NewCategory"},
}

Errors

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

Delete Category

`DELETE /categories/:id`

Deletes the category with the specified ID from the system.

Response

204 No Content Indicates that the category was successfully deleted. The response body is intentionally empty.

Errors

404 Not Found. The specified id does not correspond to any existing category.

{
    "errors": [
        "Couldn't find Category with 'id'=99"
    ]
}

Tag

Tags are hash-like labels (e.g., #green, #alert) that can be assigned to nodes to enable versatile and advanced classification and filtering. Each tag is unique and can be reused across multiple nodes, allowing for powerful metadata-based querying and organization.

Tag blueprint output

{
  "id": 1,
  "name": "NewTag"
}

List Tags

`GET /tags`

Retrieves a list of all tags. Note: Pagination and query parameters are not yet supported in this version

Response

Returns an array of Tag objects, each serialized according to the blueprint format described previously.

Status: 200 OK

[
  {
    "id": 1,
    "name": "NewTag"
  },
  {
    "id": 2,
    "name": "OtherTag"
  }
]

Create Tag

`POST /tags`

Request Body

"tag": {
  "name": "NewTag"
}

Required Fields

name (string): Must be present and unique.

Response

Returns the blueprint format described previously for the created tag.

Status: 201 Created

{
  "id": 1
  "name": "NewTag"
}

Errors

400 Bad Request: Missing parameters.

{
    "errors": [
        "param is missing or the value is empty: tag"
    ]
}

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

Show Tag

`GET /tags/:id`

Retrieves details of a single tag by its ID.

Response

Returns name and id of the requested tag. Structure matches the blueprint format described previously.

Status: 200 OK

{
    "id": 1,
    "name": "NewTag"
}

Errors

404 Not Found: The specified id does not correspond to any existing tag

{
    "errors": [
        "Couldn't find Category with 'id'=99"
    ]
}

Update Tag

`PATCH /tags/:id`

Request Body

"tag": {
 "name": "UpdatedTag"
}

Response

Returns the attributes of the updated tag. Structure matches the blueprint format described previously.

Status: 200 OK

{
  "id": 1
  "name": "UpdatedTag"
}

Errors

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

`PUT /tags/:id`

Request Body

All required attributes must be provided. Any fields not included will be removed or set to null, if allowed by the model. This endpoint fully replaces the existing Tag resource

"tag": {
 "name": "OtherUpdatedTag"
}

Response

Returns the attributes of the updated tag. Structure matches the blueprint format described previously.

Status: 200 OK

{
  "id": 1
  "name": "OtherUpdatedTag"
}

Errors

422 Unprocessable Entity: Invalid parameters.

{
    "errors": [
       <Validation message>
    ]
}

Delete Tag

`DELETE /tags/:id`

Deletes the tag with the specified ID from the system.

Response

Status: 204 No Content Indicates that the tag was successfully deleted. The response body is intentionally empty.

Errors

404 Not Found. The specified id does not correspond to any existing tag.

{
    "errors": [
        "Couldn't find Category with 'id'=99"
    ]
}

Contact / Support

In case of issues, questions, or suggestions, please contact the API maintainer at: [email protected].

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
app		app
bin		bin
config		config
db		db
lib/tasks		lib/tasks
log		log
public		public
spec		spec
storage		storage
tmp		tmp
vendor		vendor
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
Dockerfile		Dockerfile
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
Rakefile		Rakefile
config.ru		config.ru
docker-compose.yml		docker-compose.yml

manchagd/grouping_nodes_api

Folders and files

Latest commit

History

Repository files navigation

Api Design / QA Plan

API OVERVIEW

Usage

Resources

Response Format

Success Responses

JSON Serialization

API CORE RESOURCES

Node

Node blueprint output

List Nodes

GET /nodes

Response

Create Node

POST /nodes

Show Node

GET /nodes/:id

Response

Errors

Update Node

PATCH /nodes/:id

PUT /nodes/:id

Delete Node

DELETE /nodes/:id

Response

Errors

Category

Category blueprint outputs

Default:

Basic:

Extended:

List Categories

GET /categories

Response

Create Category

POST /categories

Request Body

Required Fields

Optional fields:

Response

Errors

Show Category

GET /categories/:id

Response

Errors

Update Category

PATCH /categories/:id

Request Body

Response

Errors

PUT /categories/:id

Request Body

Response

Errors

Delete Category

DELETE /categories/:id

Response

Errors

Tag

Tag blueprint output

List Tags

GET /tags

Response

Create Tag

POST /tags

Request Body

Required Fields

Response

Errors

Show Tag

GET /tags/:id

Response

Errors

Update Tag

PATCH /tags/:id

`GET /nodes`

`POST /nodes`

`GET /nodes/:id`

`PATCH /nodes/:id`

`PUT /nodes/:id`

`DELETE /nodes/:id`

`GET /categories`

`POST /categories`

`GET /categories/:id`

`PATCH /categories/:id`

`PUT /categories/:id`

`DELETE /categories/:id`

`GET /tags`

`POST /tags`

`GET /tags/:id`

`PATCH /tags/:id`

`PUT /tags/:id`

`DELETE /tags/:id`

Packages