{"id":17330387,"url":"https://github.com/voidint/rest-api-guide","last_synced_at":"2026-01-07T04:34:55.811Z","repository":{"id":90859676,"uuid":"111754777","full_name":"voidint/rest-api-guide","owner":"voidint","description":"个人的REST API风格指南","archived":false,"fork":false,"pushed_at":"2017-11-23T02:45:43.000Z","size":2,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T11:12:52.178Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voidint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-23T02:39:23.000Z","updated_at":"2017-11-23T02:39:23.000Z","dependencies_parsed_at":"2023-03-03T20:17:56.305Z","dependency_job_id":null,"html_url":"https://github.com/voidint/rest-api-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidint%2Frest-api-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidint%2Frest-api-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidint%2Frest-api-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voidint%2Frest-api-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voidint","download_url":"https://codeload.github.com/voidint/rest-api-guide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245791932,"owners_count":20672669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T14:51:06.732Z","updated_at":"2026-01-07T04:34:50.792Z","avatar_url":"https://github.com/voidint.png","language":null,"readme":"# REST API风格指南\n- URL中集合资源的操作使用名词复数。\n\n\tDon't\n\t\n\t```\n\t// 查询所有用户\n\tGET /examples/user \n\tGET /examples/user/list\n\t\n\t// 查询所有用户的所有图书\n\tGET /examples/user/book\n\tGET /examples/user/book/list\n\t```\n\t\n\tDo\n\t\n\t```\n\t// 查询所有用户\n\tGET/examples/users\n\t\n\t// 查询所有用户的所有图书\n\tGET /examples/users/books \n\t```\n\n- URL中对单个资源的操作可以使用单数。\n\n\tDon't\n\t\n\t```\n\t// 查询id为101的用户的学校信息\n\tGET /examples/users/101/schools\n\t```\n\t\n\tDo\n\t\n\t```\n\t// 查询id为101的用户的学校信息(假定某一时刻所在的学校只有一个)\n\tGET /examples/users/101/school\n\t```\n\n- URL中资源的命名需要由多个单词构成时，使用中划线(`-`)连接。\n\n\tDon't\n\t\n\t```\n\t// 查询id为101的用户的用户名\n\tGET /examples/users/101/user_name\n\tGET /examples/users/101/userName\n\t```\n\t\n\tDo\n\t\n\t```\n\t// 查询id为101的用户的用户名\n\tGET /examples/users/101/user-name\n\t```\n\n\n- URL中不要出现动词，使用`HTTP Methods`表示对URL资源的操作动作。\n\n\tDon't\n\t\n\t```\n\t// 更新用户信息\n\tPOST /examples/users/update \n\tPOST /examples/updateUser\n\t```\n\t\n\tDo\n\t\n\t```\n\t// 更新用户信息\n\tPUT /examples/users\n\t```\n- 对于资源集合中的某一具体资源的操作，建议将具体资源的标识符放入URL中。\n\n\tDon't\n\t\n\t```\n\t// 查询id为101的用户信息\n\tGET /examples/users?id=101\n\t\n\t// 查询id为101的用户的所有图书\n\tGET /examples/users/books?id=101\n\t```\n\n\tDo\n\t\n\t```\n\t// 查询id为101的用户信息\n\tGET /examples/users/101\n\t\n\t// 查询id为101的用户的所有图书\n\tGET /examples/users/101/books\n\t```\n\t\n- URL中的每一级遵循资源范围上`从大到小`、`从广到窄`的排列原则，URL的末尾是当前操作的目标。\n\t\n\tDon't\n\t\n\t```\n\t// 查询id为101的用户的所有图书的所有作者\n\tGET /examples/books/authors/users/101 // 这个查询操作的目标应该是图书作者，而非用户。\n\t```\n\t\n\tDo\n\t\n\t```\t\n\t// 查询id为101的用户的所有图书的所有作者\n\t// 资源范围从广到窄应该是\"所有用户的集合\"--\u003e\"某个用户\"--\u003e\"某个用户拥有的所有图书\"--\u003e\"某个用户拥有图书的作者集合\"，而当前操作的目标应该是\"作者\"这一资源\n\tGET /examples/users/101/books/authors\n\t```\n\n- `Request`和`Response`字段一律小写(若由多个单词组成，则用下划线(`_`)连接多个单词)。\n\n\tDon't\n\t\n\t```\n\tGET /examples/users?UserName=voidint \n\t```\n\n\tDo\n\t\n\t```\n\tGET /examples/users?user_name=voidint\n\t```\n\t\n- 操作失败情况下，不能使用`200`作为`HTTP Status code`，使用合适的[HTTP Status Codes](https://httpstatuses.com/)。\n\n\tDon't\n\t\n\t```\n\t// 查询系统中并不存在的id为101的用户\n\tGET /examples/users/101 \n\tResponse HTTP Status Code: 200\n\tResponse Body: {\"status\": \"success\", \"message\": \"user(id=101) not found\"}\n\t```\n\n\tDo\n\t\n\t```\n\t// 查询系统中并不存在的id为101的用户\n\tGET /examples/users/101 \n\tResponse HTTP Status Code:404\n\tResponse Body: {\"status\": \"success\", \"message\": \"user(id=101) not found\"}\n\t```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoidint%2Frest-api-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoidint%2Frest-api-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoidint%2Frest-api-guide/lists"}