Hi,
I have some thoughts here:
1. We could use POST /apisix/admin/routes instead of /route, due to the
previous one is more RESTful
2. It’s ok to omit the /api/ in the first case
3. Use list and total_count instead of items and total_size, more
meaningful for me :)
Xiran Liu <liuxi...@apache.org>于2021年8月25日 周三下午6:16写道：
> 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.
> > > > > > > > > >> > > >
> > > > > > > > > >> > >
> > > > > > > > > >> >
> > > > > > > > > >>
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
--
来自 琚致远
