search

littlemanco / www.littleman.co

Website
1 stars 1 forks source link

As a user I'd like to know more about API design #48

Closed andrew-howden closed 5 years ago

andrew-howden commented 5 years ago

Specifically, it'd be good to document API development guidelines that included:

  1. The default to gRPC
  2. The need for the gateway
  3. "Help" object. Smth like:
package help.v1alpha1.types;

message ErrorHint {
  // A URI (practically URL) to a service that shows help about this particular API message
  // For example
  // https://help.littleman.co/api/v1alpha1/types/FooError
  required string uri = 1

  // A message describing the nature of the error
  // For example
  //
  // The thing failed.
  required string message = 2
}

message ErrorHintList {
  repeated errors ErrorHint = 1
}
andrewhowdencom commented 5 years ago

gRPC allows returning arbitrary error payload stuff, but need to read into it more:

https://jbrandhorst.com/post/grpc-errors/

zalando-andrewhowden-com commented 5 years ago

Apparently there's a spec for this: https://tools.ietf.org/html/rfc7807