Documenting contracts
Unlike soap style messages where the Web Services Description Language (WSDL) defines a robust contract between the consumer and service provider as an XML document, there was no such metadata exchanged when consuming a REST service until WSDL 2.0 was released.
Textual documentation still seems to be popular with developers to describe the available methods and entities. There is a NuGet package available for MS Visual Studio, which automatically generates help page content for Web API projects. It can be installed using the Package Manager Console using the following command: PM> Install-Package Microsoft.AspNet.WebApi.HelpPage
.
Swagger, which is an open source product is also very popular among developers for generating interactive documentation and client SDK generation and discoverability. More information can be found at http://swagger.io/. Swagger appears to be Microsoft's tool of choice for API documentation as it has been adopted in many products in the Azure suite.
Another tool is RESTful API Modeling Language (RAML), which provides a contract first approach of modeling web APIs. This uses a derivative of YAML (YAML ain't markup language) and JSON to create a human- and machine-readable document. More information can be found at http://raml.org/index.html.
To help the consumers of the service, the messages should be self-descriptive, and you should be able to understand the requests and responses after spending minimal time using the service and reading the documentation. In the end, the URL structure has a large part to play in the overall usability of the service.
- 零基礎搭建量化投資系統:以Python為工具
- 深度學習經典案例解析:基于MATLAB
- Rust編程:入門、實戰與進階
- Building a Game with Unity and Blender
- R語言游戲數據分析與挖掘
- Flux Architecture
- RISC-V體系結構編程與實踐(第2版)
- 零基礎學Python網絡爬蟲案例實戰全流程詳解(入門與提高篇)
- Learning JavaScript Data Structures and Algorithms
- Learning Laravel's Eloquent
- jQuery Mobile移動應用開發實戰(第3版)
- Internet of Things with ESP8266
- UNIX Linux程序設計教程
- 計算機應用基礎項目化教程
- 分布式架構原理與實踐