Summary will be used as the title in the sidebar (https://gravitino.apache.org/docs/0.7.0-incubating/api/rest/list-catalogs), it should not be too long.

updated

Since this is a "list" operation rather than a "get", we won't get a "404" error, right?
If there are no credentials, returning an empty list should be desirable and it is not supposed to be treated as a "NotFound" error.

Yes, it's odd to return 404 for list operations. removed NoSuchCredential from the API

I observe that the request path specifies the metalake name; if the metalake is nonexistent, should a 404 error be returned?

updated, and noticed some tag API missing NoSuchXX too, also fixed in this PR.

If a metalake or a schema or whatever upper-level entity is not found, this request should return a 400. It is a misconfigured REST request, because the path cannot be matched by the Web layer.
404 means not found, it means and only means the meta object is not found.

404 accurately indicates that the requested resource, including any part of the URL path, cannot be found on the server.

400 Bad Request, on the other hand, is more suitable for malformed requests, such as invalid syntax or improper formatting, rather than for resources that simply don't exist.

metalake is also a meta object

404 accurately indicates that the requested resource, including any part of the URL path, cannot be found on the server.

No. If the URL path is incorrectly formatted, such as containing illegal characters, the request is not valid. The error is from the client side. So the return value should be 400.

404 has a crystal clear definition - the target resource is not found. The target resource is a singular object of a specific type. You cannot use 404 to indicate that the metalake is not found or the schema is not found or the meta-object is not found.

This is an obvious abuse of the HTTP status code.

404 is widely used for NoSuchMetalakeException exception, How about creating a separate issue to track this?

This is an obvious abuse of the HTTP status code.

Your interpretation of "target resource" seems too narrow in the context of RESTful APIs. The HTTP specification (RFC 7231) states that 404 applies when "the origin server did not find a current representation for the target resource." In REST, each path segment is considered a resource, not just the final element.

GitHub's API provides a clear example of this practice. Consider their endpoint for getting a repository:

GET /repos/{owner}/{repo}

If either the {owner} or {repo} doesn't exist, GitHub returns a 404 status code. For instance, requesting https://api.github.com/repos/nonexistent-user/some-repo returns 404, even though the error is in the 'owner' part of the path, not the final resource.

You can verify this behavior and see the documentation here:
https://docs.github.com/en/rest/repos/repos#get-a-repository

This approach aligns with RESTful design principles, providing clear feedback about resource availability throughout the URL path, and is consistent with industry best practices.

I believe we have a enum for this field.

we didn't define an enum because we should support custom credentials. add the build-in credentials

Please amend the description so that users know what this long number is.

updated

Gocha. :)

This is not supposed to be a time elapsed since epoch.
It is supposed to be time duration in milliseconds when the credential (e.g. a certificate) will expire.

It's not an time duration, because the credential may need some time to transfer from server side to client side, which makes duration not correct.

Thanks for mentioning the credential type examples.

Although not in the scope of this PR, I'm still wondering if we need to add an API for users to retrieve a list of supported credential types.

I couldn't figure out usage scenarios about this API, we could add it if requried.

I wouldn't call this credentialType because the property has a well-defined scope.
E.g. when I'm modeling a Person, I'll simply add a gender property rather than
naming it as personGender.

This can be pretty simple, e.g.
{"type": "gcs-token", "expireTimeInMs": 12345, "data": {"token": "secret"}}

Yes, thanks for pointing this out, I agree with you, how about keeping this as it has been published as API? I will try to use the short style for new features.