Proposal and planning for API framework

[ddysher]

Introduction

api framework, or http web framework, is a long standing engineering backlog across engineering teams. The proposal aims to shed some light on how we want to move forward. This is by no means a thorough design, we hope to gather enough feedback to get going. Feel free to comment.

Background

No guideline is provided at this moment to start up a new apiserver from scratch, results in a divergent approaches on setting up new web projects. No conventions enforced at framework level also results in bugs due to breaking apis, validation errors, etc. On the other hand, engineering effort is wasted on solving the same range of problems which should ideally be solved in an API framework.

Goal

• Reduce api level errors and inconsistency
• Improve engineering productivity via removing repeated work, adding code generation, etc
• Adding new resource type should only require defining struct definition
• Adding validation should only require declaring validation method as part of struct definition
• Consistent behavior, structure and layout across all golang server projects
• Out-of-box server instrumentation, e.g. metrics, tracing, profiling, etc

Proposal

Survey

Below is a short survey on existing projects:

• kubernetes-admin style (go-restful)
  • routing wrapper around go-restful
  • a well-defined layout
  • count for 70% of all related projects
• loadbalancer-admin style (gin)
  • use gin directly
  • no well-defined project layout
  • count for 20% of all related projects
• liubo style (go-restful)
  • mirrors closely with kubernetes style
  • count for 10% of all related projects

Requirements

Following is all the required functionalities for our framework.

Routing, Request & Response

• Routes mapping from request to function
  • support for path parameter (e.g. /api/v1/animals/{id})
  • support for query parameter (e.g. /api/v1/animals?type=dog)
  • support regex
• Grouping Routes
  • routes can be grouped for better arragement, but doesn't have to be first class concept
• Request/Response API object
  • to/from structs in json
  • easy access to path,query,header parameters
• Middleware support
  • general middleware support is required for developer to add custom middleware
  • required default middleware: request logging, recovery, tracing
• Contextual process chain and parameter injection
  • all handlers accepts a context value representing a request context
  • requset parameters can be validated and injected into handler, see below
• API error convention
  • define canonical error code and type based on api convention
• multipart/urlencoded form support (low priority)
• file upload support (low priority)
• grpc support (low priority)

Instrumentation

• Provide default metrics at well-known endpoints for prometheus to scrape
  • need to define set of default metrics
• Tracing should be provided by default to allow better troubleshooting
  • follow opentracing, which is industry standard
  • use jaeger as tracing system
• Profiling can be enabled in debug mode for troubleshooting
  • use go profile

Validation

• Provide default validation on api types with json, e.g. required, within a range, etc
• Support custom validations defined by developers on api types
• support validation on all parameters (path, query, etc)

Usability

• A working project should be brought up with a few lines of code using the framework
• Framework must follow engineering conventions to help developers focus on business logic
• OpenAPI (swagger 2.0) specification can be generated automatically with no extra work
• Provides a well-established layout conforming to golang project layout
• Easy and standard configuration
• A reasonable support for websocket

Performance

• Performance is not a hard requirement for initial stage; but it should not introduce observable latency

None-requirements

A list of functionalities commonly seen in other frameworks that are not in our scope

• https support. While it's not hard to serve https in go, https is out of scope since all services are expected to be running behind API gateway
• html rendering, orm, etc. Let's stick it to a simple restful framework
• testing. testing should be a different library

Design and Implementation

Project Timeline

• Due 09.15: launch the project (@ddysher)
• Due 09.23: draft feature set (@ddysher)
• Due 09.29: finalize feature set and roadmap (@ddysher)
• Due 12.01: check in most features (framework, cli, validation, metrics)
• Due 12.20: check in all features, with reasonable test coverage (openapi, tracing)
• Due 01.31: documentation, examples, website should be ready

Feature Design and Planning

Following is a list of planned features, their respective design and planning.

• Basic framework
• API Validation
• Configuration Management
• OpenAPI Generation
• Instrumentation and Profiling
• Tracing

Meetings

Regular meetings will be held to discuss above topics.

• 1st meeting
• 2nd meeting
• 3rd meeting
• 4th meeting
• 5th meeting
• 6th meeting

Assignees

• Project tracking and proposal maintenance (@ddysher)
• Overall structure, project layout, etc (@ddysher)
• Routing, multiplexing, middleware, API error package, etc (@kdada)
• Configuration management (@zuomo)
• API validation (@walktall)
• OpenAPI generation (@liubog2008 @jimexist )
• Prometheus instrumentation (@caitong93)
• tracing (@yejiayu)

References

• go-restful
• gin
• chi
• validator
• code-generator
• prometheus
• jaeger

[zoumo]

we should support OpenAPI 3.0 specification.

[walktall]

How about https://github.com/go-chi/chi?

[xiaoq17]

Shall we track this in sprint, or kill it in freestyle?

[jimexist]

• common middlewares
• required and optional parameter parsing
• swagger integration

[jimexist]

• suggestion/style guide for CQRS?

[jimexist]

Non-golang, but highly recommended read about other great HTTP API frameworks:

• Plug used in Phoenix Framework
• Connect used by Express.js

[ddysher]

@zoumo It's too early to say open api 3.0 should be supported, plus you can't find a reliable library at this moment. 2.0 is enough for us now.

we should support OpenAPI 3.0 specification.

@walktall looks like chi only offers router. The main consideration for listing go-restful here is that we can leverage kubernetes's codegen; but we can definitely look at other packages.

How about https://github.com/go-chi/chi?

@xiaoq17 framework is quite important now, i'd like to track it in sprint, for 1. predictable delivery time (hopefully); 2. help negotiate tasks with other product requirements. we can decide this next week.

Shall we track this in sprint, or kill it in freestyle?

@jimexist these are already mentioned in the issue

common middlewares
swagger integration

@jimexist can you elaborate the use case?

required and optional parameter parsing

[jimexist]

@ddysher regarding required and optional parameter, the one i missed most is from Dropwizard

[kdada]

@jimexist Golang has tags for struct fields. But there is no tags for parameters of methods/functions. It's even no parameter name in reflection.

We have two ways to achieve it:

• Use a user-defined descriptor to describe methods/functions.
• Use a pre-compiler as a wrapper for golang compiler to generate code.

[ddysher]

@caicloud/review-framework I've updated our timeline, PTAL.

[ddysher]

Done 🚀

I'll create a doc to archive the issue.