0

我正在设计一个新的 API，我正在为一些决定而苦苦挣扎。我已经阅读了大量关于 SOAP 与 REST 的博客，并使用流行的 API（Paypal、Amazon 等）作为我的指导方针。

我最终在我的 API 中使用了 2 个端点：一个用于 SOAP，一个用于 REST (XML)。SOAP 看起来不错，但 XML 接口看起来有些奇怪。我称它为“奇怪”，因为我最终在一些标签中使用了命名空间。例如：

[样本1]

<EnvelopeRequest xmlns:c1='http://foobar/CarrierX'>
    <Weight>1.0</Weight>
    <PostmarkDate>5/3/2013</PostmarkDate>
    <c1:ShippingMethod>Ground</c1:ShippingMethod>
    <c1:Notification>a@b.com</c1:Notification>
</EnvelopeRequest>

[样本2]

<EnvelopeRequest xmlns:cs='http://foobar/SpecialCarrier'>
    <Weight>1.0</Weight>
    <PostmarkDate>5/3/2013</PostmarkDate>
    <cs:Shape>Flat</cs:Shape>
</EnvelopeRequest>

XML 接口具有命名空间的原因是因为它是从类定义（具有一些继承性）自动生成的。顺便说一句，我们正在使用 WCF。这对于 SOAP（WSDL 派生自同一个类）非常有效，因为 SOAP 隐藏了客户端代理中的所有丑陋。但是，在查看了许多 REST/XML 服务之后，我认为我没有看到过经常使用名称空间。这也让我有点害怕，因为我在想我希望在不久的将来有一个 JSON 接口，而 JSON 不支持命名空间。

我之所以决定使 API SOAP 友好，是因为我们的许多客户都使用在 SOAP 上蓬勃发展的企业解决方案。但最近，随着 Python 和 Ruby 的日益流行，新客户似乎更频繁地采用它们，我开始怀疑我最初的决定。困扰我的主要是 XML 接口中的命名空间，但这真的是个问题吗？REST/XML API 中的命名空间是一个很大的禁忌，我应该改变我的设计吗？

如果我确实改变了我的设计，那么我的（前 2 个）请求将如下所示：

[样本1]

<EnvelopeRequest>
    <Weight>1.0</Weight>
    <PostmarkDate>5/3/2013</PostmarkDate>
    <CarrierX>
        <ShippingMethod>Ground</ShippingMethod>
        <Notification>a@b.com</Notification>
    </CarrierX>
</EnvelopeRequest>

[样本2]

<EnvelopeRequest>
    <Weight>1.0</Weight>
    <PostmarkDate>5/3/2013</PostmarkDate>
    <SpecialCarrier>
        <Shape>Flat</Shape>
    </SpecialCarrier>
</EnvelopeRequest>

是的，这将允许我在未来拥有一个 JSON 接口。

4

2 回答 2

2

Removing namespaces would be a problem if by doing so you create the possibility of ambiguity in a given message. Is it possible for someone somewhere to create an EnvelopeRequest message with a Shape element that might be interpreted (by code or by people reading the message) in more than one way? The reason to introduce namespaces is to preclude this possibility. Tools like WCF's auto-generator are not able to answer this question in the general case so they err on the side of caution.

Only you can know the set of possible valid messages. In my experience, it's usually preferable to remove namespaces for the sake of not confusing your users/clients. There are a few reasons why I might change that preference:

  • I expect my message format to be used widely and intermixed with other formats. (A good example is the Atom syndication format)
  • I'm using someone else's widely used (and namespaced) format and planning to intermix it with my own (e.g. embedding XHTML inside my message).
  • I expect to embed a message of a given format inside a message of the same format (e.g. XSLT stylesheets that generate XSLT stylesheets).

In that latter case, you might find it convenient (though not absolutely necessary) to use namespaces to separate the inner message from the message that is carrying it by using different prefixes. I don't think any of these cases apply very often.

于 2013-05-04T01:13:51.623 回答
0

我会思考为什么你首先有命名空间，那些是一些奇怪的有效载荷。

But, disregarding that, no, the namespaces are not a big deal. Namespaces almost inevitably run afoul with XPath and XSL (since they tend to be namespace aware), but when consuming the document wholesale, a lot of times folks just ignore the namespace component completely, so in the end there's no difference.

I would clean up the namespaces for the sake of cleaning them up semantically, but not necessarily for the sake of the consumers. From a practical stand point, it's not that big a deal.

于 2013-05-03T23:44:26.553 回答