README

描述MyParcel.com使用的API规范，位于https://carrier-specification.myparcel.com。本规范遵循OpenApi 3.0规范并实现了JSON API规范。

内容

安装
命令
约定
许可证

安装

仓库提供Docker容器，用于在提交更改前验证和预览规范。这同样用于验证拉取请求。要安装Docker，请按照文档中的步骤进行。

要为开发设置项目，请运行

./mp.sh setup

命令

./mp.sh up - 启动容器，这将启动一个服务器以监视文件更改并自动重新加载。

./mp.sh down - 停止容器。

./mp.sh validate - 验证规范。

注意：验证器仅在容器已运行时才有效。不要忘记启动它们。

约定

基于Swagger和JSON Schema规范约定的。

以下描述了我们的内部约定。

PUT, POST, PATCH

为了避免讨论，以下描述了上述HTTP方法的使用。

`PUT`

用于创建或替换资源。
重复请求始终返回相同的响应。
请求需要完整的资源（包括要创建或替换的资源id）。

`POST`

用于创建资源。
重复请求不返回相同的响应。
请求不需要完整的资源（通常不需要要创建的资源id）。

`PATCH`

用于更新现有资源。
重复请求不返回相同的响应。
请求不需要完整的资源（例如，你可能只想更新用户的姓名）。

API版本控制

API版本控制遵循语义版本控制。版本号的增加是手动进行的，并且应该是拉取请求的一部分。

模式文件命名

定义文件名遵循PascalCasing。每个单词的第一个字母（包括第一个单词）都是大写。例如，国家代码的定义可以在以下位置找到：

specification/schemas/CountryCode.json

路径文件命名

specification/paths中的文件根据其相应的API端点命名。资源以大写字母开头，路径变量以小写字母开头。例如，以下路由的定义可以在以下位置找到：

carriers/{carrier_id}/services

可以找到以下定义：

specification/paths/Carriers-carrier_id-Services.json

参数文件命名

参数文件名以相应的参数类型为前缀。对于carrier_id的路径参数，文件路径如下：

specification/parameters/path-carrier_id.json

唯一的参数可以仅保留在路径文件中，无需提取到自己的文件中。

许可证

MyParcel.com所有的软件均受MyParcel.com通用条款和条件的许可。

myparcelcom / carrier-specification

维护者

详细信息