JSON REST/RPC接口的IDL [英] IDL for JSON REST/RPC interface

问题描述

我们正在设计一个相当复杂的REST API，其中大多数I/O是具有特定结构的JSON编码对象.我们发现的一个挑战是以一种使客户更容易张贴正确的输入和处理输出的方式来记录API.由于输入和输出的数据都需要相当复杂的JSON对象，因此客户端开发人员经常会引入与I/O对象结构相关的错误.

We are designing a fairly complex REST API, in which most of the I/O are JSON encoded objects with a specific structure. One challenge we have found is to document the API in such a way that makes it easier for clients to post correct input and process output. Because the data of both the input and output requires fairly complex JSON objects, client developers often introduce bugs related to the structure of the I/O objects.

这些天来，随着JSON Web API的发展，我本来希望有一个通用的解决方案，但是我很难找到一个解决方案.我查看了 json-schema ，它是一个json验证模式，但是IETF草案和实现似乎都还不成熟(即使它们已经存在了一段时间，这不是一个好兆头).

With all of the JSON web API's these days, I would have hoped for a general solution, but I am having a hard time finding one. I looked into json-schema which is a json-validation schema but both the IETF draft and implementations seem to be fairly immature (even though they have been around for a while, which is not a good sign).

协议缓冲区和

A slightly different approach is offered by Protocol Buffers and Apache Avro, where the schema is not used for validation, but actually required for the encoding/decoding of the message. Of these 2, Avro seems to have rather limited documentation and implementations. ProtoBuf seems better, but I am not sure if this is really suitable to use in the browser to call a JSON api?

现在，我开始怀疑我是否从正确的角度看待这个问题.还有其他方法可以使我的API变得更强壮吗?还是对JSON REST/RPC API的正式描述会破坏使用JSON的目的?

Now I am starting to doubt if I am looking at this from the right angle. Are there other methods available to make my API a bit more strong-typed'ish? Or is a formal description of a JSON REST/RPC API something that defeats the purpose of using JSON?

在该主题发布6个月后，我们发现了 mongoose ，与我们要查找的内容非常接近.

6 months after this topic we found mongoose, which is very close to what we were lookin for.

推荐答案

下面是我从道格拉斯·克罗克福德收到的电子邮件回复.

Below a reply I received by email from Douglas Crockford.

我不相信模式可以替代输入验证. 有些属性无法通过语法进行验证.我认为 这是XML出错的方式之一.

I am not a believer in schemas as an alternative to input validation. There are properties that cannot be verified from the syntax. I think that was one of the ways that XML went wrong.

如果您的格式太复杂，那么我会考虑简化 他们.

If your formats are too complex, then I would look at simplifying them.

这篇关于JSON REST/RPC接口的IDL的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！