Update Implement

Update the details of an existing agricultural implement. This endpoint uses partial updates (COALESCE), meaning you only need to include the fields you want to change.

Authentication Required: This endpoint requires a valid JWT Bearer token with administrator privileges (role_id: 1).

Endpoint

PUT /api/implements/{id}

Path Parameters

integer

required

The unique identifier of the implement to update

Authentication

Include your JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Request Body

All fields are optional. Only include the fields you want to update.

implement_name

string

Name of the implementValidation: Cannot be empty if provided

brand

string

Manufacturer brand nameValidation: Cannot be empty if provided

power_requirement_hp

number

Required horsepower (HP) to operate the implementValidation: Must be a positive number if provided

working_width_m

number

Working width in metersValidation: Must be a positive number if provided

implement_type

string

Type of implement. Must be one of:

plow
harrow
seeder
sprayer
harvester
cultivator
mower
trailer
other

soil_type

string

Compatible soil type(s)Example: “Loam”, “Clay”, “All”

working_depth_cm

number

Working depth in centimetersValidation: Must be a positive number if provided

weight_kg

number

Implement weight in kilogramsValidation: Must be a positive number if provided

status

string

Current status. Must be one of:

available
maintenance
inactive

Response

success

boolean

Indicates if the update was successful

message

string

Success or error message

data

object

The updated implement object with all current field values

Examples

Update Power Requirement and Working Depth

curl -X PUT http://localhost:4000/api/implements/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "power_requirement_hp": 90,
    "working_depth_cm": 35
  }'

Change Status to Maintenance

curl -X PUT http://localhost:4000/api/implements/3 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"status": "maintenance"}'

Update Multiple Fields

curl -X PUT http://localhost:4000/api/implements/5 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "implement_name": "Sembradora mejorada 8 hileras",
    "power_requirement_hp": 70,
    "working_width_m": 2.6,
    "soil_type": "All",
    "weight_kg": 620
  }'

Response Example (200 OK)

{
  "success": true,
  "message": "Implemento actualizado exitosamente",
  "data": {
    "implement_id": 1,
    "implement_name": "3-body disc plow",
    "brand": "Baldan",
    "power_requirement_hp": 90,
    "working_width_m": 0.9,
    "soil_type": "Loam",
    "working_depth_cm": 35,
    "weight_kg": 320,
    "implement_type": "plow",
    "status": "available",
    "registration_date": "2026-01-15T10:00:00.000Z"
  }
}

The response includes the complete implement object with all fields, not just the fields that were updated.

Error Responses

Invalid ID (400)

{
  "success": false,
  "message": "ID de implemento inválido"
}

Validation Error (400)

{
  "success": false,
  "message": "Errores de validación",
  "errors": [
    "power_requirement_hp debe ser un número positivo",
    "implement_type debe ser uno de: plow, harrow, seeder, sprayer, harvester, cultivator, mower, trailer, other"
  ]
}

Unauthorized (401)

{
  "success": false,
  "message": "Token inválido o expirado"
}

Forbidden - Not Admin (403)

{
  "success": false,
  "message": "Acceso denegado: se requiere rol de administrador"
}

Not Found (404)

{
  "success": false,
  "message": "Implemento no encontrado"
}

Internal Server Error (500)

{
  "success": false,
  "message": "Error al actualizar implemento"
}

Partial Updates (COALESCE)

This endpoint uses PostgreSQL’s COALESCE function for partial updates. This means:

Only send fields you want to change - Other fields remain unchanged
Empty request body - No changes are made (but still returns 200 OK)
Null values - Interpreted as “no change”, not as setting the field to null

Example: Update Only Status

If you only want to change the status from available to maintenance:

{
  "status": "maintenance"
}

All other fields (implement_name, power_requirement_hp, etc.) remain unchanged.

SQL Implementation

The update query (from src/models/Implement.js:62):

UPDATE implement 
SET implement_name = COALESCE($1, implement_name),
    brand = COALESCE($2, brand),
    power_requirement_hp = COALESCE($3, power_requirement_hp),
    working_width_m = COALESCE($4, working_width_m),
    soil_type = COALESCE($5, soil_type),
    working_depth_cm = COALESCE($6, working_depth_cm),
    weight_kg = COALESCE($7, weight_kg),
    implement_type = COALESCE($8, implement_type),
    status = COALESCE($9, status)
WHERE implement_id = $10
RETURNING *

COALESCE($1, implement_name) means: “Use $1 if provided, otherwise keep the current value of implement_name”.

Validation Rules

Field Validation

When updating, fields are validated only if provided:

String fields cannot be empty if provided
Numeric fields must be positive if provided
Enum fields (implement_type, status) must be valid values

Implement Type Values

plow, harrow, seeder, sprayer, harvester, cultivator, mower, trailer, other

Status Values

available, maintenance, inactive

Implementation Notes

Source: src/routes/implement.routes.js:426 - Route definition
Controller: src/controllers/implementController.js:205 - updateImplement function
Model: src/models/Implement.js:49 - update(id, implementData) method
Validation: Fields are validated only if provided in request body
Middleware Chain:
1. verifyTokenMiddleware - Validates JWT token
2. isAdmin - Checks for admin role
3. validateImplement - Validates provided fields
4. updateImplement - Updates the implement
Cache Invalidation: Invalidates both *implements* and *recommendations* cache patterns

Updating implements that are referenced in existing recommendations will invalidate recommendation caches to ensure data consistency.

Common Update Scenarios

Mark as Under Maintenance

curl -X PUT http://localhost:4000/api/implements/{id} \
  -H "Authorization: Bearer {token}" \
  -d '{"status": "maintenance"}'

Adjust Power Requirements

After field testing, adjust the power requirement:

{
  "power_requirement_hp": 95
}

Update Specifications

Update technical specifications after recalibration:

{
  "working_depth_cm": 32,
  "weight_kg": 465
}

Reactivate Inactive Implement

{
  "status": "available"
}

List Implements

View all implements

Get Implement

Retrieve implement details before updating

Create Implement

Add a new implement (Admin only)

Delete Implement

Remove an implement (Admin only)

Changes to implements are reflected immediately in power calculations and recommendation queries.

Authentication

Tractors

Implements

Terrains

Calculations

Recommendations

Roles

​Update Implement

​Endpoint

​Path Parameters

​Authentication

​Request Body

​Response

​Examples

​Update Power Requirement and Working Depth

​Change Status to Maintenance

​Update Multiple Fields

​Response Example (200 OK)

​Error Responses

​Invalid ID (400)

​Validation Error (400)

​Unauthorized (401)

​Forbidden - Not Admin (403)

​Not Found (404)

​Internal Server Error (500)

​Partial Updates (COALESCE)

​Example: Update Only Status

​SQL Implementation

​Validation Rules

​Field Validation

​Implement Type Values

​Status Values

​Implementation Notes

​Common Update Scenarios

​Mark as Under Maintenance

​Adjust Power Requirements

​Update Specifications

​Reactivate Inactive Implement

​Related Endpoints

List Implements

Get Implement

Create Implement

Delete Implement

Build docs developers (and LLMs) love

Update Implement

Endpoint

Path Parameters

Authentication

Request Body

Response

Examples

Update Power Requirement and Working Depth

Change Status to Maintenance

Update Multiple Fields

Response Example (200 OK)

Error Responses

Invalid ID (400)

Validation Error (400)

Unauthorized (401)

Forbidden - Not Admin (403)

Not Found (404)

Internal Server Error (500)

Partial Updates (COALESCE)

Example: Update Only Status

SQL Implementation

Validation Rules

Field Validation

Implement Type Values

Status Values

Implementation Notes

Common Update Scenarios

Mark as Under Maintenance

Adjust Power Requirements

Update Specifications

Reactivate Inactive Implement

Related Endpoints