Skip to main content

​
Overview

The devgraph-api block defines API routes for a service. Routes attach to a parent service defined by devgraph-service. In the hybrid build, API blocks enrich the authoritative service layer inside graph.json. They do not replace the repo scan or file-level graph.

​
Syntax

```devgraph-api
service: my-service
routes:
  GET /health: Health check endpoint
  GET /api/users: List all users
  POST /api/users: Create a new user
  PUT /api/users/:id: Update a user
  DELETE /api/users/:id: Delete a user
```

​
Fields

FieldRequiredDescription
serviceYesName of the parent service
routesYesObject mapping routes to descriptions

​
Route Format

Routes are defined as METHOD /path: description: 
routes:
  GET /path: Description of what this endpoint does
  POST /path: Another endpoint description

​
Supported Methods

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

​
Path Parameters

Use :param syntax for path parameters: 
routes:
  GET /users/:id: Get user by ID
  PUT /posts/:postId/comments/:commentId: Update a comment

​
Examples

​
REST API

```devgraph-api
service: api
routes:
  GET /health: Health check
  GET /api/users: List users
  GET /api/users/:id: Get user by ID
  POST /api/users: Create user
  PUT /api/users/:id: Update user
  DELETE /api/users/:id: Delete user
```

​
Multiple API blocks

You can split routes across multiple blocks: 
```devgraph-api
service: api
routes:
  GET /api/users: List users
  POST /api/users: Create user
```

```devgraph-api
service: api
routes:
  GET /api/posts: List posts
  POST /api/posts: Create post
```

​
Generated Output

API routes appear in:
  • graph.json top-level apis
  • graph.json top-level services under the matching service
  • summary.md in the routes section
  • agents/{service}.md and generated skills