Skip to main content

​
Overview

The Custom Language Service is a demonstration microservice that processes invocation requests and returns customized responses. It supports error simulation for testing different HTTP status codes and records all executions to a database.

​
Base URL

http://custom-lang-service:3000

​
Endpoints

​
Health Check

curl -X GET http://custom-lang-service:3000/healthz

ok
Checks the health status of the custom language service and database connection. Response Codes:
  • 200 - Service is healthy
  • 503 - Database health check failed

​
Invoke Service

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "World"
  }'

{
  "message": "Hello World from custom-lang-service!"
}
Processes an invocation request and returns a personalized greeting message. Records each execution to the database (if configured).
​
name
string
default:"World"
Name to include in the greeting message. Special values trigger error responses for testing purposes.
​
message
string
Greeting message (only present on successful 200 responses)
​
error
string
Error description (only present on error responses)
Response Codes:
  • 200 - Success
  • 401 - Unauthorized (triggered by name=“unauthorized”)
  • 403 - Forbidden (triggered by name=“forbidden”)
  • 404 - Not Found (triggered by name=“notfound”)
  • 409 - Conflict (triggered by name=“conflict”)
  • 429 - Rate Limited (triggered by name=“ratelimit”)
  • 503 - Service Unavailable (triggered by name=“unavailable”)

​
Special Testing Values

The /invoke endpoint includes built-in error simulation for testing various HTTP status codes. Use these special name values to trigger specific error responses:
Name ValueStatus CodeError Message
unauthorized401unauthorized
forbidden403forbidden
notfound404not found
conflict409conflict
ratelimit429rate limited
unavailable503service unavailable
Any other value will result in a successful 200 response with a greeting message.

​
Usage Examples

​
Successful Invocation

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice"
  }'

{
  "message": "Hello Alice from custom-lang-service!"
}

​
Default Name

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "message": "Hello World from custom-lang-service!"
}

​
Error Simulation - Unauthorized

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "unauthorized"
  }'

{
  "error": "unauthorized"
}

​
Error Simulation - Rate Limit

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ratelimit"
  }'

{
  "error": "rate limited"
}

​
Error Simulation - Service Unavailable

curl -X POST http://custom-lang-service:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "name": "unavailable"
  }'

{
  "error": "service unavailable"
}

​
Database Recording

All invocations are recorded to the database (when configured) with the following information:
  • name - The name parameter from the request
  • result_message - The greeting message (null for errors)
  • status_code - The HTTP status code returned
The service continues to function even if database recording fails, logging errors to the console without affecting the response.

​
Error Handling

Error responses follow a consistent format: 
{
  "error": "error description"
}
Error Response Status Codes:
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 429 - Too Many Requests
  • 503 - Service Unavailable (health check failure or simulated error)

​
Notes

  1. Content Type: All requests must include Content-Type: application/json header
  2. Database: The service operates with or without database configuration. Failed database operations are logged but don’t interrupt request processing
  3. Type Coercion: The name parameter is converted to a string using .toString()
  4. Testing: Special name values are designed for integration testing and error handling verification
  5. Execution History: When the database is configured, all invocations are stored in the executions table for auditing and analytics

Build docs developers (and LLMs) love

Get started for freeTalk to us