我的这个 API 设计有什么缺陷/有什么优化空间吗？

[rv54ntjwfm3ug8]

因为后端使用 C# + ASP.NET Core 写的，大小写学的是官方 Web API 模板。

POST /api/License/Activate

Example:

• Request Body:

{
    "productId": 2,
    "productBuildVersion": 45,
    "userHardwareUuid": "659d8d48-d301-4ee1-afdd-c44b958bc948",
    "requestSignature": "e65143a751d32af2ebbc7ffddedf45cbb1b43a20"
}

• Response Body:

  • Success (HTTP 200):

{
    "result": "success",
    "pgpSignedLicense": "wsFcBAEBCAAQBQJiVnEnCRDWDnwt3C20igAAWG8P/2wZvL5x6ky1KZtf9Mx/\\nUYXFjk84G2BOrm557hxhoz1TixxRR7kQ7nXqi0nkz4iV+D1Fn5mzN5es4Toc\\n/B+gTecXP5Q119FjORGyj5Dy9tWyUc1rVyqmYWwWwpLIM3mFmpfGIek1JjUg\\ngczVsiHWVNOnbeE81iHhfwklN2PHH6ARAepTNnM/PhI173CSkA/Jp/Xpe+CZ\\nRJqZP0GxcT+NuMMivS716Jl96c0HkpNpnrtfU9fLsiWmcxeul3cXKusiti09\\nmudOteT2Jk7Atq1BN9S06BXxNg3zcvRlt9yFUaubgBkvZ/KzPzm3+qO+Djad\\nSDVEICDqZwS+NV2Fo5tiDys43inRjhi3naLjgUIysNuibwkRGJAjCVQij/3X\\nfBOdzm2CW5r7w/QLzot8zqADiZt8Smm7mgbILXY+VqQKHDCm2rME5V6q4GSh\\nBNREbJ6Nif26D+hsTZSzUkEHtp0J4dTcxjzBdiiG7SoHVsS55U0KwiAzfO0x\\nUGrTuGO+iBJ9ii1YYDz+8A5Jy7c5neVhl6KNpJdsZzPkXyIIOKgsNZZDBxOJ\\nf3tpNpIg6TimW0+fej36B17VzLBIuair1RR8lO7aPCe9S6ZnpEugr2nHys4m\\nm4I6wY7AiYHlC3dmYjvcS8GqSs/fytFENJXnLMlbddtSNKIihwI4n1DKG+48\\n4cdx\\n=jkGa",
    "validUntil": 1681368168000
}

• Fail 0 (HTTP 200):

{
    "result": "general_error",
    "errors": ["reach_max_client_count"]
}

• Fail 1 (HTTP 400):

{
    "result": "bad_request",
    "errors": ["invalid_user_hardware_uuid"]
}

• Fail 2 (HTTP 500):

{
    "result": "internal_error"
}

[Chad0000]

op 你竟然在 200 返回错误，小心隔壁来怼

[equationl]

哈哈哈哈，你隔壁帖子就是在说状态码的

[rv54ntjwfm3ug8]

@equationl #2 对，我一个多月前就问过这个问题 /t/838609 ，按照大家的建议我这样设计了 API ，今天看到了隔壁的帖子才想来问问我这样设计有什么缺陷吗？

[seakingii]

@theklf4 没什么缺陷,隔壁说的最大的也就是不好监控和解析状态码了,不是特别大的系统无所谓.

[seakingii]

我是建议定义一套自己的整型的状态码,而不是回传错误信息,方便客户端搞多语言,以及做分支处理

[equationl]

@theklf4 看了楼主原帖，发现原来楼主做的是激活软件的 API ，我突然想起来很久之前我写的同功能的 API 直接就是全部 200 一把梭哈，当时甚至就没意识到可以用不同的状态码标记不同的错误

[seakingii]

@equationl 呵呵,以前还把业务内容加密并压缩放在 http post 的 body 里.业务需要自己选择,不用听他们的教条主义.

[Chad0000]

@equationl
我之前就知道了但还是返回 200 ，因为简单可控，post 可以传任意复杂的数据。你完全 rest 了，然后第一件事情就是仔细选好你的 code ，这对业务并没什么帮助。

[dcalsky]

1. Exception response 既有 200 又有 400, 500 ，很奇怪
2. result 字段用来只放请求成功与否，所以完全没必要存在；而 errors 字段设计又太简单。

[pengtdyd]

@Chad0000 隔壁绝不可能过来怼，因为隔壁都是搞 JAVA 的，这个是 c#写的他们看不上！

[rv54ntjwfm3ug8]

@dcalsky #9 既有 200 又有 400, 500 是因为 400/500 请求无法被服务器 handle 。errors 字段还应该返回什么东西呢，我觉得挺详细的了

[rv54ntjwfm3ug8]

@seakingii #5 为什么说定义一套整形状态码方便搞多语言呢？

[isno]

返回值能改成下划线风格么？驼峰看着头疼

[isno]

Url 里面怎么也有大小写

[rv54ntjwfm3ug8]

@isno #13 #14 C#官方的例子就是这样的

[Bingchunmoli]

因为 http 非 200 在某些语言中（至少我写的语言不能或者说没有人教怎么携带 message ），所以我们都是 200 然后业务 code （自定义，阿里巴巴规范成功是 00000 ）,也有一种说法，可预见，可处理都是 200 其他是 http 状态码不可预见的

[rv54ntjwfm3ug8]

@dcalsky #9 如果没有 result 字段的话要怎么判断成功与否呢，判断 errors 字段？

[Chad0000]

不管用不用 200 ，建议返回值格式统一：
{
"result" : 0, // 0 表示成功，其他表示失败，具体失败描述看 massage
"message" : "操作成功",
"data" : {} // 可以是任意类型，取决于你要返回什么数据
}

URL 我个人建议全部小写。

[Chad0000]

@Bingchunmoli
我赞同你的说法，200 是可预见可处理的，其他都是意外，可以统一处理或不处理（系统异常）。

[aneureka]

可以参考 Google Cloud API Style Guide： https://cloud.google.com/apis/design

建议 200 OK 这种情况还是不要杂糅一个二级错误码来标识错误情况了，比较推荐的做法应该是把你的业务错误映射到对应的 HTTP Error Code 里去，具体可以看下上面的链接 👆🏻