Path Parameters

Learn how to use path parameters (URL) in moclojer to create dynamic endpoints that respond to different ID, slug, and other data values.

Path parameters allow you to create dynamic endpoints that respond to different values in the URL. For example, a single endpoint /users/:id can respond to both /users/1 and /users/999.

Why Use Path Parameters?

Before (without path params):

- endpoint:
    path: /users/1
    response:
      body: '{"id": 1, "name": "Alice"}'

- endpoint:
    path: /users/2
    response:
      body: '{"id": 2, "name": "Bob"}'

# ... you would need 1000 endpoints for 1000 users! 😱

After (with path params):

- endpoint:
    path: /users/:id
    response:
      body: >
        {
          "id": "{{path-params.id}}",
          "name": "User {{path-params.id}}"
        }

# A single endpoint responds to ANY ID! 🎉

Basic Syntax

Declaring a Path Parameter

Use a colon (:) before the parameter name:

path: /users/:id

Format: /path/:parameterName

Accessing the Value

Use templates {{path-params.parameterName}}:

- endpoint:
    method: GET
    path: /users/:id
    response:
      status: 200
      body: >
        {
          "id": "{{path-params.id}}",
          "message": "You requested user {{path-params.id}}"
        }

Test:

curl http://localhost:8000/users/123
# Response: {"id": "123", "message": "You requested user 123"}

curl http://localhost:8000/users/alice
# Response: {"id": "alice", "message": "You requested user alice"}

Path Parameter Types

Moclojer supports type validation using the :param|type syntax:

String (default)

path: /users/:username        # Accepts any string
path: /users/:username|string # Explicit (same behavior)

Matches:

/users/alice ✅
/users/bob123 ✅
/users/João ✅

Integer

path: /users/:id|int

Matches:

/users/1 ✅
/users/999 ✅
/users/0 ✅

Doesn't match:

/users/abc ❌
/users/1.5 ❌
/users/ ❌

UUID

path: /sessions/:sessionId|uuid

Matches:

/sessions/550e8400-e29b-41d4-a716-446655440000 ✅

Doesn't match:

/sessions/abc123 ❌
/sessions/123 ❌

Boolean

path: /features/:enabled|boolean

Matches:

/features/true ✅
/features/false ✅

Doesn't match:

/features/yes ❌
/features/1 ❌

Multiple Path Parameters

You can have multiple parameters in the same path:

- endpoint:
    method: GET
    path: /users/:userId/posts/:postId
    response:
      status: 200
      body: >
        {
          "userId": "{{path-params.userId}}",
          "postId": "{{path-params.postId}}",
          "post": {
            "id": "{{path-params.postId}}",
            "author": "User {{path-params.userId}}",
            "title": "Post {{path-params.postId}} by User {{path-params.userId}}"
          }
        }

Test:

curl http://localhost:8000/users/42/posts/7

Response:

{
  "userId": "42",
  "postId": "7",
  "post": {
    "id": "7",
    "author": "User 42",
    "title": "Post 7 by User 42"
  }
}

Practical Examples

Example 1: Products API

- endpoint:
    method: GET
    path: /products/:productId|int
    response:
      status: 200
      headers:
        Content-Type: application/json
      body: >
        {
          "id": {{path-params.productId}},
          "name": "Product {{path-params.productId}}",
          "sku": "PRD-{{path-params.productId}}",
          "price": 29.99,
          "inStock": true
        }

Usage:

curl http://localhost:8000/products/101
# {"id": 101, "name": "Product 101", "sku": "PRD-101", ...}

Example 2: Blog with Slugs

- endpoint:
    method: GET
    path: /blog/:slug|string
    response:
      status: 200
      body: >
        {
          "slug": "{{path-params.slug}}",
          "title": "{{path-params.slug}}",
          "content": "This is the content of post {{path-params.slug}}",
          "publishedAt": "2024-01-15T10:00:00Z"
        }

Usage:

curl http://localhost:8000/blog/introduction-to-moclojer
curl http://localhost:8000/blog/path-parameters-guide

Example 3: Complete RESTful API

# GET /users/:id - Get user
- endpoint:
    method: GET
    path: /users/:id|int
    response:
      status: 200
      body: >
        {
          "id": {{path-params.id}},
          "name": "User {{path-params.id}}",
          "email": "user{{path-params.id}}@example.com"
        }

# PUT /users/:id - Update user
- endpoint:
    method: PUT
    path: /users/:id|int
    response:
      status: 200
      body: >
        {
          "id": {{path-params.id}},
          "name": "{{json-params.name}}",
          "email": "{{json-params.email}}",
          "updated": true
        }

# DELETE /users/:id - Delete user
- endpoint:
    method: DELETE
    path: /users/:id|int
    response:
      status: 204   # No Content

Example 4: Nested Resources

# GET /organizations/:orgId/teams/:teamId/members/:memberId
- endpoint:
    method: GET
    path: /organizations/:orgId|int/teams/:teamId|int/members/:memberId|int
    response:
      status: 200
      body: >
        {
          "organizationId": {{path-params.orgId}},
          "teamId": {{path-params.teamId}},
          "memberId": {{path-params.memberId}},
          "member": {
            "id": {{path-params.memberId}},
            "name": "Member {{path-params.memberId}}",
            "team": "Team {{path-params.teamId}}",
            "organization": "Org {{path-params.orgId}}"
          }
        }

Usage:

curl http://localhost:8000/organizations/1/teams/5/members/42

Combining with Other Parameters

Path parameters work together with query params and body params:

- endpoint:
    method: GET
    path: /users/:userId|int/posts
    response:
      status: 200
      body: >
        {
          "userId": {{path-params.userId}},
          "limit": "{{query-params.limit}}",
          "offset": "{{query-params.offset}}",
          "posts": [
            {"id": 1, "title": "Post 1"},
            {"id": 2, "title": "Post 2"}
          ]
        }

Usage:

curl "http://localhost:8000/users/42/posts?limit=10&offset=0"

Response:

{
  "userId": 42,
  "limit": "10",
  "offset": "0",
  "posts": [...]
}

Route Precedence

When multiple endpoints can match, moclojer uses the first occurrence:

# ⚠️ Order matters!

# 1. Specific route (should come FIRST)
- endpoint:
    path: /users/me
    response:
      body: '{"currentUser": true}'

# 2. Generic route (should come AFTER)
- endpoint:
    path: /users/:id
    response:
      body: '{"id": "{{path-params.id}}"}'

How it works:

GET /users/me → matches endpoint #1 ✅
GET /users/123 → matches endpoint #2 ✅

If you reverse the order:

# ❌ PROBLEM: generic route comes first!
- endpoint:
    path: /users/:id
    response:
      body: '{"id": "{{path-params.id}}"}'

- endpoint:
    path: /users/me
    response:
      body: '{"currentUser": true}'  # Will NEVER be used!

Result:

GET /users/me → matches endpoint #1 (:id = "me") ❌ Wrong!

Golden rule: Specific routes before dynamic routes!

Validation and Errors

Incorrect Type

If you define a type and the value doesn't match:

- endpoint:
    path: /users/:id|int

Requests:

/users/123 → ✅ Match
/users/abc → ❌ No match (moclojer returns 404)

Creating Specific Error Endpoints

# Specific endpoint for ID not found
- endpoint:
    method: GET
    path: /users/999
    response:
      status: 404
      body: >
        {
          "error": "User not found",
          "message": "User with ID 999 does not exist"
        }

# Generic endpoint (should come after)
- endpoint:
    method: GET
    path: /users/:id|int
    response:
      status: 200
      body: >
        {
          "id": {{path-params.id}},
          "name": "User {{path-params.id}}"
        }

Best Practices

✅ Do

Use explicit types when possible

path: /users/:id|int      # ✅ Validates it's a number

Descriptive parameter names

path: /posts/:postId      # ✅ Clear
path: /posts/:id          # ⚠️ Less clear in nested resources

Specific routes before dynamic ones

- path: /users/me         # ✅ First
- path: /users/:id        # ✅ After

Use parameter value in response

body: >
  {"id": "{{path-params.id}}"}  # ✅ Response reflects the input

❌ Avoid

Parameters without type when should have one

path: /users/:id          # ⚠️ Accepts "abc" as ID
path: /users/:id|int      # ✅ Only accepts numbers

Names too generic

path: /api/:param1/:param2  # ❌ What are these?
path: /api/:userId/:postId  # ✅ Self-documenting

Too many nesting levels

path: /a/:b/c/:d/e/:f/g/:h  # ❌ Hard to read
path: /users/:id/posts      # ✅ Maximum 2-3 levels

Troubleshooting

Problem: "404 Not Found" when it should work

Possible causes:

Incorrect parameter type

path: /users/:id|int
# Trying: /users/abc → 404 (correct, not an int)

Wrong route order

# If /users/:id is before /users/me
# /users/me will match with :id="me"

Different HTTP method

method: GET
path: /users/:id
# POST /users/123 → 404 (wrong method)

Problem: Template `{{path-params.id}}` is not replaced

Cause: Parameter name doesn't match

# ❌ Wrong
path: /users/:userId
body: '{"id": "{{path-params.id}}"}'  # Should be userId!

# ✅ Correct
path: /users/:userId
body: '{"id": "{{path-params.userId}}"}'

Problem: Parameter comes as string when wanted number

Cause: Template strings always return strings

# ❌ Returns string "123"
body: >
  {
    "id": "{{path-params.id}}"
  }

# ✅ Returns number 123
body: >
  {
    "id": {{path-params.id}}
  }

Note: Without quotes = number, with quotes = string.

Next Steps

Now that you've mastered path parameters:

Query Parameters - Parameters in the URL after ?
Body Parameters - Data in the request body
Template Variables - Complete template reference

hashtagWhy Use Path Parameters?

hashtagBasic Syntax

hashtagDeclaring a Path Parameter

hashtagAccessing the Value

hashtagPath Parameter Types

hashtagString (default)

hashtagInteger

hashtagUUID

hashtagBoolean

hashtagMultiple Path Parameters

hashtagPractical Examples

hashtagExample 1: Products API

hashtagExample 2: Blog with Slugs

hashtagExample 3: Complete RESTful API

hashtagExample 4: Nested Resources

hashtagCombining with Other Parameters

hashtagRoute Precedence

hashtagValidation and Errors

hashtagIncorrect Type

hashtagCreating Specific Error Endpoints

hashtagBest Practices

hashtag✅ Do

hashtag❌ Avoid

hashtagTroubleshooting

hashtagProblem: "404 Not Found" when it should work

hashtagProblem: Template {{path-params.id}} is not replaced

hashtagProblem: Parameter comes as string when wanted number

hashtagNext Steps

hashtagSee Also

Why Use Path Parameters?

Basic Syntax

Declaring a Path Parameter

Accessing the Value

Path Parameter Types

String (default)

Integer

UUID

Boolean

Multiple Path Parameters

Practical Examples

Example 1: Products API

Example 2: Blog with Slugs

Example 3: Complete RESTful API

Example 4: Nested Resources

Combining with Other Parameters

Route Precedence

Validation and Errors

Incorrect Type

Creating Specific Error Endpoints

Best Practices

✅ Do

❌ Avoid

Troubleshooting

Problem: "404 Not Found" when it should work

Problem: Template `{{path-params.id}}` is not replaced

Problem: Parameter comes as string when wanted number

Next Steps

See Also