API Guide

统一风格的 REST 文档入口，既保留 REST Docs 生成内容，也提升目录、表格与代码块的可读性。

本页围绕资源结构、请求示例、响应内容与常见约定组织阅读路径。 生成内容仍然来自测试与 snippets，当前优化主要聚焦在信息层级、视觉统一与浏览体验。

查看资源目录 回到项目首页

目录更易扫读

左侧 TOC 采用胶囊式高亮与更清晰的缩进层级，适合长文档快速定位。

表格与代码块更现代

参数表、字段表与请求示例统一为深色卡片容器，便于长时间阅读。

不改坏生成链路

REST Docs 的 operation/include 内容保持原有插入方式，仅通过结构与 CSS 做增强。

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. Read More

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to replace an existing resource.

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. Read More

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

String

The time, in milliseconds, at which the error occurred

For example, a request that attempts to apply a non-existent tag to a note will produce a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 164

{"timestamp":"2026-04-23T13:45:21.309+00:00","status":400,"error":"Bad Request","path":"/depts","message":"The tag 'http://localhost:8080/depts/-1' does not exist"}

Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource. Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate

Resources

Index

The index provides the entry point into the service.

Accessing the index

A GET request is used to access the index

Response fields

Path Type Description

_links

Object

Links to other resources

Response example

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 325

{
  "_links" : {
    "employees" : {
      "href" : "http://localhost:8080/employees{?page,size,sort*}",
      "templated" : true
    },
    "depts" : {
      "href" : "http://localhost:8080/depts{?page,size,sort*}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/profile"
    }
  }
}
Relation Description

depts

The Depts resource

employees

The Employees resource

profile

The ALPS profile for the service

Page

Page 资源用于描述分页信息。

Path Description

size

每页显示数量

totalElements

总条数

totalPages

总页数

number

当前所在页

部门（Depts）

Depts 资源用于创建、删除、修改部门资源, 以及列出部门资源列表、查询单个部门资源的信息和使用特定条件搜索部门信息。

创建部门

POST 请求将用于创建一个部门记录。

Request fields

Path Type Description

name

String

部门名称

Request example

$ curl 'http://localhost:8080/depts' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "This is a test dept."
}'

Response example

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/depts/1
Content-Type: application/hal+json
Content-Length: 307

{
  "id" : 1,
  "name" : "This is a test dept.",
  "new" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "dept" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "employees" : {
      "href" : "http://localhost:8080/depts/1/employees"
    }
  }
}

删除一个部门信息

DELETE 请求用于删除一个部门资源。

Path parameters

Table 1. /depts/{id}
Parameter Description

id

部门编号

Request example

$ curl 'http://localhost:8080/depts/1' -i -X DELETE \
    -H 'Content-Type: application/hal+json'

Response example

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

修改部门信息

PATCH 请求用于更新部门资源的一个或多个属性。

Path parameters

Table 1. /depts/{id}
Parameter Description

id

部门编号

Request fields

要保持部门资源的属性不变，可以从请求中体中省略 Request fields 中任何一个。

Path Type Description

name

String

新的部门名称

Request example

$ curl 'http://localhost:8080/depts/1' -i -X PATCH \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "This is renamed dept."
}'

Response example

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 308

{
  "id" : 1,
  "name" : "This is renamed dept.",
  "new" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "dept" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "employees" : {
      "href" : "http://localhost:8080/depts/1/employees"
    }
  }
}

通过部门编号, 检索单个部门的完整信息

GET 请求将检索并返回完整的部门资源的详细信息。

Path parameters

Table 2. /depts/{id}
Parameter Description

id

部门编号

Response fields

Path Type Description

id

Number

部门编号

name

String

部门名称

new

Boolean

是否新建
Relation Description

dept

部门 资源

employees

员工资源（Employees） 的列表

Request example

$ curl 'http://localhost:8080/depts/1' -i -X GET

Response example

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 294

{
  "id" : 1,
  "name" : "部门1",
  "new" : false,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "dept" : {
      "href" : "http://localhost:8080/depts/1"
    },
    "employees" : {
      "href" : "http://localhost:8080/depts/1/employees"
    }
  }
}

部门列表

GET 请求将用于列出所有部门。

Query parameters

Parameter Description

page

要查询的页数

size

每页显示条数

sort

排序条件

Response fields

Path Type Description

_embedded.depts

Array

部门资源的列表, 详情查看《通过部门编号, 检索单个部门的完整信息》

_links

Object

Links to other resources

page

Object

Page to other resources
Relation Description

profile

The ALPS profile for this resource

first

第一页

prev

上一页

next

下一页

last

最后一页

Request example

$ curl 'http://localhost:8080/depts?page=1&size=5' -i -X GET

Response example

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
Content-Length: 2429

{
  "_embedded" : {
    "depts" : [ {
      "id" : 6,
      "name" : "部门6",
      "new" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/depts/6"
        },
        "dept" : {
          "href" : "http://localhost:8080/depts/6"
        },
        "employees" : {
          "href" : "http://localhost:8080/depts/6/employees"
        }
      }
    }, {
      "id" : 7,
      "name" : "部门7",
      "new" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/depts/7"
        },
        "dept" : {
          "href" : "http://localhost:8080/depts/7"
        },
        "employees" : {
          "href" : "http://localhost:8080/depts/7/employees"
        }
      }
    }, {
      "id" : 8,
      "name" : "部门8",
      "new" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/depts/8"
        },
        "dept" : {
          "href" : "http://localhost:8080/depts/8"
        },
        "employees" : {
          "href" : "http://localhost:8080/depts/8/employees"
        }
      }
    }, {
      "id" : 9,
      "name" : "部门9",
      "new" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/depts/9"
        },
        "dept" : {
          "href" : "http://localhost:8080/depts/9"
        },
        "employees" : {
          "href" : "http://localhost:8080/depts/9/employees"
        }
      }
    }, {
      "id" : 10,
      "name" : "部门10",
      "new" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/depts/10"
        },
        "dept" : {
          "href" : "http://localhost:8080/depts/10"
        },
        "employees" : {
          "href" : "http://localhost:8080/depts/10/employees"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/depts?page=0&size=5"
    },
    "prev" : {
      "href" : "http://localhost:8080/depts?page=0&size=5"
    },
    "self" : {
      "href" : "http://localhost:8080/depts?page=1&size=5"
    },
    "next" : {
      "href" : "http://localhost:8080/depts?page=2&size=5"
    },
    "last" : {
      "href" : "http://localhost:8080/depts?page=3&size=5"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/depts"
    }
  },
  "page" : {
    "size" : 5,
    "totalElements" : 20,
    "totalPages" : 4,
    "number" : 1
  }
}