Hi Community,
It's been a while since the restful api discussion was updated.
It seems that we have reached an agreement that we will use HTTP Status code
instead of the current response body param `code`, when the request got status
200, it will return the request data, and when it got error, it will return the
error message in the response body.
I tried to list the two method of Route Module in current Manager-api, stand
for two scenarios, focused on the response parameters, let's see whether it
meets agreement,
1. get list of all routes, all list request response refer to this.
```text
GET /apisix/admin/api/routes
```
Response:
Status: 200 OK - application/json
```json
{
"items": [{"schema of the route"}],
"total_size": 1,
}
```
Status: 500 Internal Server Error
```json
{
"message": "Internal Server Error"
}
```
2. create a route, POST PATCH PUT. and GET resource item info response refer to
this.
```text
POST /apisix/admin/route
```
Response:
Status: 200 OK - application/json
```json
{
"name": "route1",
...other route schema
}
```
Note: for the POST PUT PATCH method, will return the updated resource schema,
for the GET info method, will return the request item schema.
Status: 500 Internal Server Error
```json
{
"message": "Internal Server Error"
}
```
If we have no doubt about this style. I will go on to refine all the interfaces
of the route module and at the same time consistent experience with both
Manager API and Admin API.
Looking forward to your reply, thanks a lot
On 2021/07/27 08:56:58, Shyamal Madura Chinthaka <shyamal.mad...@gmail.com>
wrote:
> Hi Zhiyuna,
>
> Yes. step by step. cheers!
>
> On Tue, Jul 27, 2021 at 1:51 PM Zhiyuan Ju <juzhiy...@apache.org> wrote:
>
> > Got it, I would prefer to adjust the first revision and make it RESTful.
> > HATEOAS may be the final version haha :)
> >
> > Best Regards!
> > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> >
> >
> > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com> 于2021年7月27日周二
> > 下午4:03写道：
> >
> > > Hi Zhiyuan,
> > >
> > > Good day to you and all!
> > >
> > > Yes, you are spot on. This eventually increases the robustness of the API
> > > to decouple service client static awareness uses the server-provided
> > links
> > > to dynamically discover available actions and access the resources it
> > > needs.
> > >
> > > Regards,
> > > Shyamal
> > >
> > > On Tue, Jul 27, 2021 at 10:31 AM Zhiyuan Ju <juzhiy...@apache.org>
> > wrote:
> > >
> > > > Hi, Shyamal,
> > > >
> > > > Just to make sure, do you mean you want the response body including
> > > > something like `_herf` or `links` to other resources?
> > > >
> > > > ```json
> > > > {
> > > > "id" : 1,
> > > > "body" : "My first blog post",
> > > > "postdate" : "2015-05-30T21:41:12.650Z",
> > > > "_links" : {
> > > > "self": { "href": "http://blog.example.com/posts/1"; },
> > > > "comments": { "href": "
> > http://blog.example.com/posts/1/comments
> > > ",
> > > > "totalcount" : 20 },
> > > > "tags": { "href": "http://blog.example.com/posts/1/tags"; }
> > > > }
> > > > }
> > > > ```
> > > >
> > > > Best Regards!
> > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > >
> > > >
> > > > Shyamal Madura Chinthaka <shyamal.mad...@gmail.com> 于2021年7月27日周二
> > > > 上午2:36写道：
> > > >
> > > > > Hi Team,
> > > > >
> > > > > +1 to rely on HTTP status code instead of the code in the response
> > > body.
> > > > >
> > > > > This will take our burden of enforcing governance to define/maintain
> > > > > additional code in the response body which will unlikely to
> > effectively
> > > > > override the HTTP status code.
> > > > >
> > > > > However - if possible - enriching the response of these APIs to adopt
> > > > > HATEOAS would be progressive immensely.
> > > > >
> > > > >
> > > > > Regards,
> > > > > Shyamal
> > > > >
> > > > > On Mon, Jul 26, 2021, 07:20 Zhiyuan Ju <juzhiy...@apache.org> wrote:
> > > > >
> > > > > > Hi,
> > > > > >
> > > > > > Users have 2 ways to use our product: Using Dashboard or Call API
> > > > > directly.
> > > > > >
> > > > > > We have JSONSchema checker on the backend, if users call API
> > directly
> > > > and
> > > > > > check failed, it will return the JSONSchema error; if users use
> > > > > Dashboard,
> > > > > > why not validate data on Web? So I think there has no need to add a
> > > > > > specific login code in the Response Body :)
> > > > > >
> > > > > > Best Regards!
> > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > >
> > > > > >
> > > > > > Chao Zhang <zchao1...@gmail.com> 于2021年7月26日周一 上午9:41写道：
> > > > > >
> > > > > > > HTTP status code will be fine if we don’t care the very specific
> > > > error
> > > > > > > type.
> > > > > > >
> > > > > > > Chao Zhang
> > > > > > > https://github.com/tokers
> > > > > > >
> > > > > > > On July 25, 2021 at 17:34:40, Jintao Zhang (
> > > > zhangjintao9...@gmail.com)
> > > > > > > wrote:
> > > > > > >
> > > > > > > I agree!
> > > > > > > At the same time, I also think that HTTP Status code should be
> > used
> > > > > > instead
> > > > > > > of the logical code field.
> > > > > > >
> > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月25日周日 下午3:29写道：
> > > > > > >
> > > > > > > > Hi,
> > > > > > > >
> > > > > > > > Any further discussion on this mail? I'm going to list all APIs
> > > and
> > > > > > check
> > > > > > > > which part we should modify.
> > > > > > > >
> > > > > > > > Best Regards!
> > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > > >
> > > > > > > >
> > > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年7月22日周四 下午2:47写道：
> > > > > > > >
> > > > > > > > > I would prefer relying on Status Code instead of `code`
> > > (actually
> > > > > > it's
> > > > > > > a
> > > > > > > > > manual logical and extendable code).
> > > > > > > > >
> > > > > > > > > Why not list all API cases then have a choice?
> > > > > > > > >
> > > > > > > > > Best Regards!
> > > > > > > > > @ Zhiyuan Ju <https://github.com/juzhiyuan>
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > Ming Wen <wenm...@apache.org> 于2021年7月22日周四 下午12:36写道：
> > > > > > > > >
> > > > > > > > >> please give an example about i18n for a better understanding
> > > > > > > > >>
> > > > > > > > >> Thanks,
> > > > > > > > >> Ming Wen, Apache APISIX PMC Chair
> > > > > > > > >> Twitter: _WenMing
> > > > > > > > >>
> > > > > > > > >>
> > > > > > > > >> JunXu Chen <chenju...@apache.org> 于2021年7月22日周四 上午11:36写道：
> > > > > > > > >>
> > > > > > > > >> > Agree +1
> > > > > > > > >> >
> > > > > > > > >> >
> > > > > > > > >> > I think we still need to keep the `code` field.
> > > > > > > > >> >
> > > > > > > > >> > The FE needs to implement i18n according to it.
> > > > > > > > >> >
> > > > > > > > >> > Unless `message` is semantic and can be used as a key of
> > > i18n.
> > > > > > > > >> >
> > > > > > > > >> >
> > > > > > > > >> >
> > > > > > > > >> > On Thu, 22 Jul 2021 at 00:02, Ming Wen <
> > wenm...@apache.org>
> > > > > > wrote:
> > > > > > > > >> >
> > > > > > > > >> > > I don't think the `code` filed is useful, HTTP response
> > > code
> > > > > is
> > > > > > > > >> enough.
> > > > > > > > >> > >
> > > > > > > > >> > > Thanks,
> > > > > > > > >> > > Ming Wen, Apache APISIX PMC Chair
> > > > > > > > >> > > Twitter: _WenMing
> > > > > > > > >> > >
> > > > > > > > >> > >
> > > > > > > > >> > > Peter Zhu <sta...@apache.org> 于2021年7月21日周三 下午11:18写道：
> > > > > > > > >> > >
> > > > > > > > >> > > > Agree +1.
> > > > > > > > >> > > > And I think we should maintain the `code` filed and
> > > > maintain
> > > > > > the
> > > > > > > > >> doc of
> > > > > > > > >> > > > API.
> > > > > > > > >> > > >
> > > > > > > > >> > >
> > > > > > > > >> >
> > > > > > > > >>
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
