RESTful

最新推荐文章于 2025-07-08 14:34:18 发布

原创最新推荐文章于 2025-07-08 14:34:18 发布 · 263 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#json

Java 同时被 2 个专栏收录

34 篇文章

订阅专栏

.NET

9 篇文章

订阅专栏

本文详细阐述了构建易用、接受度高且灵活性强API的关键原则，包括使用RESTful URL和操作、SSL加密、优秀文档、版本控制、响应格式、错误处理等，确保API易于开发人员使用。

要使API易用、易于接受和足够灵活，应该遵循以下原则：

An API is a user interface for a developer - so put some effort into making it pleasant
Use RESTful URLs and actions
Use SSL everywhere, no exceptions
An API is only as good as its documentation - so have great documentation
Version via the URL, not via headers
Use query parameters for advanced filtering, sorting & searching
Provide a way to limit which fields are returned from the API
Return something useful from POST, PATCH & PUT requests
HATEOAS isn't practical just yet
Use JSON where possible, XML only if you have to
You should use camelCase with JSON, but snake_case is 20% easier to read
Pretty print by default & ensure gzip is supported
Don't use response envelopes by default
Consider using JSON for POST, PUT and PATCH request bodies
Paginate using Link headers
Provide a way to autoload related resource representations
Provide a way to override the HTTP method
Provide useful response headers for rate limiting
Use token based authentication, transported over OAuth2 where delegation is needed
Include response headers that facilitate caching
Define a consumable error payload
Effectively use HTTP Status codes