API Awesome

API/RPC 考虑因素

• 灵活
  • 静态结构
  • 动态结构
  • 兼容性
• 性能
  • 延时要求
  • 服务对服务
  • 服务对客户端
• 序列化
  • 二进制
  • 文本 - JSON
• 语言兼容
  • 需要支持什么语言
  • 自用只需考虑个别语言
  • 对外则需要考虑通用
• 接口模式
  • 请求响应
  • 流式请求
  • 流式响应
• 规范
  • 生成友好
  • 元数据信息完整
• 场景
  • 自用 - 满足内部使用即可
  • 对外 - 采用现有标准规范
• 生态
  • 可观察性
    • Metric
    • Trace
  • 网关
  • 中间件感知

API Gateway 考虑因素

• 管理能力
  • 负责 增删改 Endpoint - vendor lockin
  • 使用现有配置 - 控制能力弱
• 可观察性能力
  • Metric 集成
  • Trace 集成
  • 内置 - 网关采集、内置显示
  • 外部 - grafana、jeager、prometheus
• 控制能力
  • Auth
  • Threshold
  • 注入自定义逻辑 - Hook
• 协议感知能力
  • gRPC
  • HTTP
  • GraphQL
  • TCP、UDP
• 平台集成能力
  • Kubernetes Service、Annotatation
  • Consul Service
  • ETCD、ZK
• 实现模式
  • 无侵入 - 直接网络拦截
    • 网络层处理 - Cilium
  • 侵入 - 修改代码逻辑
    • 中间件 - 集成 metric、trace 等能力
    • SQL Trace
  • Sidecar - 按应用网络拦截
    • 获取基础 metric 信息、可能能实现 trace 能力
    • Agent 能代表应用身份
    • 通常还能实现 E2E 加密认证
• 元数据存储方式
  • CRD
  • DB - PostgreSQL、MySQL - 需要额外维护、但方便排查使用
  • KV - ETCD、ZK

Design

• Google AIP - API Improvement Proposals
  • cloud.google.com/apis
• Zalando RESTful API and Event Guidelines
• How to design better REST APIs
  1. 一致 - 字段名、接口名、授权、头处理、状态码、HTTP 方法
  2. ISO 8601 Date
  3. 区分不需要授权的接口
  4. 提供 GET /health
  5. API 添加版本 - 例如 /v1/health
  6. Accept API key authentication - 服务端对服务端
  7. 使用正确的 HTTP 状态码
  8. 使用正确的 HTTP 方法
  9. Use self-explanatory, simple names
  10. 使用标准的错误响应 - HTTP 状态码+对应消息体
  11. 创建成功返回创建内容
  12. PUT -> PATCH
  13. Be as specific as possible
  14. Use pagination
  15. Allow expanding resources
• stripe.com/blog/idempotency
• microsoft/api-guidelines

规范

• RFC9110 HTTP Semantics
• Financial-grade API
• Microsoft Graph
  • github microsoftgraph
  • graph-explorer
• WangNingkai/OLAINDEX
• www.asyncapi.com/docs/specifications/v2.3.0
  • swaggest/go-asyncapi
  • medium.com/event-driven-utopia/understanding-asyncapis-with-a-practical-example-ee2b4be221d8
• swagger.io/specification
• SchemaStore/schemastore
  • JSON Schema 集合，覆盖大量 API 和配置格式。
• jsonapi.org/format
• webrpc/webrpc

RPC

Note

• rpc 和 serialization 主要的区别在于 服务 是否为第一公民
• 除了 gRPC, jsonrpc 其他 rpc 实现基本都是语言相关的
  • 意味着 非第一方语言的支持相对较弱
• gRPC 是支持最多语言的 RPC 协议

RPC	by	Languages	Notes
gRPC	Google
Thrift	Facebook	Java
twirp	TwitchTV	Go - PHP,Ruby
finagle	Twitter	Scala	Apache-2.0
tarpc	Google	Rust
ice
国产
HSF	Alibaba	Java
Dubbo	Alibaba	Java
go-zero	好未来技术	Go
kitex	字节跳动	Go
sofa-rpc	蚂蚁金服	Java
tars	腾讯	C++,Java,NodeJS,PHP,Web	BSD-3
brpc	百度	C++,Java
motan	微博	Java
cat	大众点评	Java
rpcx		Go
erpc		Go

Microservice	by	Tech
armeria	Line	Java
国产
kratos	哔哩哔哩	Go,gRPC
go-chassis		Go
go-doudou		Go

• JSON RPC
• gRPC
  • by Google
  • connect - 支持 HTTP POST ，兼容 gRPC, gRPC Web
• Avro
• json-api/json-api
  • application/vnd.api+json
• only-cliches/NoProto
  • MIT, Rust
  • Flexible, Fast & Compact Serialization with RPC
• twitchtv/twirp
  • by Twitch
• finagle
  • Apache-2.0, Scala
  • by Twitter
• tRPC
• trpc-group/trpc-go
  • 不是 JS 的 tRPC，是腾讯的 RPC
• Tencent/flare

JSON-RPC

• elpheria/rpc-websockets
  • LGPLv3, TS, JS
  • JSON-RPC 2.0 over WebSockets

Serialization

• protobuf
• flatbuffer
• json
• xml
• yaml
• msgpack
• inkeliz/karmem
  • BSD-3
  • faster than Google Flatbuffers and optimized for TinyGo and WASM
• betwixt-labs/bebop
  • Typescript, C#, Rust, C++
  • betwixt-labs/tempo
    • RPC

• ASN.1 PER
• Avro, CapnProto, Protobufs, Flatbuffers
• Schema-ful, copying: Protobuf, Thrift, plenty more
• Schema-ful, zero-copy: Cap'n'proto, Flatbuffers
• Schema-less, copying: Json (binary and other variants included), XML
• Schema-less, zero-copy: Flexbuffers
• Avro is also another data serialization format. Schema-Ful,
• Arrow would be schema-ful, zero-copy
• CBOR - Concise Binary Object Representation
  • 与 JSON 混用

• djkoloski/rust_serialization_benchmark
• alecthomas/go_serialization_benchmarks

Data Gateway

• Hasura
• graphile
• PostREST
• Prisma2
• stargate/stargate
  • Java, Apache-2.0
• urigo/graphql-mesh
  • GraphQL Adapter
  • 后端支持 GraphQL, JSON Schema, gRPC, Swagger, OpenAPI, SOAP, Postgres, Mongo, OData, Thrift, SQLite, MySQL, Neo4j

OpenAPI

• JavaScript/Typescript/NodeJS
  • hey-api/openapi-ts
    • OpenAPI to TypeScript codegen. Generate clients, SDKs, validators
  • metadevpro/openapi3-ts
    • TS Model
  • APIDevTools/swagger-parser
    • MIT, JS
    • OpenAPI 2.0, 3.0 parser/validator
    • Resolves all $ref
• Codegen
  • 7nohe/openapi-react-query-codegen
    • OpenAPI -> React Query+@hey-api/openapi-ts
  • orval-labs/orval
    • ⚠️ 项目开发不活跃
    • OpenAPI -> TS
  • OpenAPITools/openapi-generator
    • OpenAPI -> Client & Server
  • drwpow/openapi-typescript
    • OpenAPI -> Typescript
  • curlconverter/curlconverter
    • cURL -> Code
  • glideapps/quicktype
    • JSON, Schema, GraphQL -> type & converter
• fern-api/fern
  • Apache-2.0, TS, JS
  • OpenAPI -> SDKs & Docs
  • Ruby, Python, TS, Java, Go, C#, PHP
• getkin/kin-openapi
  • MIT, Golang
  • OpenAPIv3 for Go
• Diff
  • OpenAPITools/openapi-diff
    • Apache-2.0, Java
  • tufin/oasdiff
    • Apache-2.0, Golang
    • www.oasdiff.com
  • Azure/openapi-diff
  • api-diff.io
  • bitbucket.org/atlassian/openapi-diff
    • openapi-diff

npx -y openapi-typescript https://github.com/openai/openai-openapi/raw/master/openapi.yaml --output apis.d.ts

# @7nohe/openapi-react-query-codegen
# ==================================
# https://openapi-react-query-codegen.vercel.app/guides/introduction
# default to @hey-api/client-fetch
npm add @hey-api/client-fetch
npx --package @7nohe/openapi-react-query-codegen openapi-rq -i ./petstore.yaml

依赖包@hey-api/client-fetch

API Gateway

API 生命周期管理

• apache/apisix
• apache/incubator-shenyu
  • 可扩展、高性能、响应式的 Java API 网关
• Kong
• Tyk
• luraproject/lura
• How to choose the right API Gateway for your platform
• api-platform/api-platform
  • Create REST and GraphQL APIs, scaffold Jamstack webapps, stream changes in real-time.

Doc

• slatedocs/slate
• widdershins
  • OpenAPI -> slate markdown
• Redocly/redoc
• swagger
• graphql
• OpenAPI
• syroegkin/swagger-markdown
  • 只支持 v2

API IDE/Client

• usebruno/bruno
  • MIT, JS, TS
  • ightweight alternative to postman/insomnia
  • 自定义的 bru 格式
    • www.brulang.org
    • Why bru
  • 通过 Desktop APP、CLI、VSC Extension
  • HN HN #39653718
  • vs Postman
• Hoppscotch
  • MIT, Vue+Typescript
  • 可以 Selfhost
  • 支持 OpenAPI, GraphQL
• mountain-loop/yaak
  • MIT, TypeScript, Rust, Tauri
• Kong/insomnia
  • MIT, JS+TS
  • GraphQL, REST, WebSockets, gRPC
  • 需要上传才能同步
• google/gnostic
• EsperoTech/yaade
  • self-hosted, collaborative API development environment
• SoapUI
• kubeshop/tracetest
• mquan/api2ai
  • Create API agents from OpenAPI Specs
• ShishirPatil/gorilla
  • API store for LLMs
• Markup
  • bru
  • JB HTTP Client
  • Orange-OpenSource/hurl
    • hurl.dev
• Testing
  • stepci/stepci
    • MPLv2, TS
    • Automated API Testing and Quality Assurance
• 商业
  • www.eolinker.com
  • Postman
  • paw.cloud
• YMFE/yapi
  • YMFE 去哪儿网
  • 商业产品 apifox
• thx/rap2-delos
  • rap2.taobao.org
• thx/RAP
• sx1989827/DOClever
• RecipeUI/RecipeUI

SOAP

• NodeJS
  • vpulim/node-soap
    • [npm
      ]
  • loopbackio/strong-soap
    • [npm
      ]
  • circa10a/easy-soap-request
    • [npm
      ]
• Public
  • NOAA National Weather Service
    • graphical.weather.gov/xml/SOAP_server/ndfdXMLserver.php?wsdl
  • USGS Water Services
    • waterservices.usgs.gov/nwis/site?format=waterml,1.1&stateCd=ca&siteType=ST&siteStatus=active
  • USGS Earthquake Hazards Program
    • earthquake.usgs.gov/ws/design
  • USGS Water Services
    • waterservices.usgs.gov/nwis/site?format=waterml,1.1&stateCd=ca&siteType=ST&siteStatus=active
  • USGS Earthquake Hazards Program
    • earthquake.usgs.gov/ws/design

Produce OpenAPI

• AndrewWalsh/openapi-devtools
  • Chrome 插件
  • 在浏览时生成接口
• alufers/mitmproxy2swagger
  • Automagically reverse-engineer REST APIs via capturing traffic
• jonluca/har-to-openapi

参考

• public-apis/public-apis
• www.postman.com/ai-engineer/generative-ai-apis/overview
• How Uber Engineering Evaluated JSON Encoding and Compression Algorithms to Put the Squeeze on Trip Data
  • 2016-02

Service Discovery

• Redis
  • pyloque/captain
• Nacos