
API Company Mistakes - Serialization Formats - craigkerstiens
http://www.rdegges.com/api-company-mistakes-part-1-serialization-formats/
======
goronbjorn
When developers ask for a serialization format other than what you're
providing, it's generally because they're using a particular language that has
a parser they like (or is the only parser they're aware of) for that
particular serialization format. Moreover, the language they're using might be
dictated by their employer and not by personal choice. A combination of those
reasons is why SOAP and XML have lived on for so long.

What you should derive from this, however, is _not_ that you need to provide
better support for that particular serialization format; rather, if you want
to make this particular set of developers happier, you need to provide better
support for that _language_ they're using. In general, this means building
SDKs for your API in whatever language your developers prefer.

When given the choice between building an integration with an XML API from
scratch, building an integration with JSON API from scratch, and building an
integration with an SDK that does most of the work for you, developers will
generally pick the last option, regardless of how the data is being serialized
underneath.

------
derefr
> After thinking this through, however, I realized that one of the largest
> mistakes an API company can make is to remove previously advertised
> functionality (why would developers trust you to provide data to them if
> you're so quick to remove functionality?).

It seems to me that when providing a new feature in your API, you should have
a latency period at the beginning where it is not guaranteed to continue to
exist. Sort of the dual to the deprecation period at the end-of-life of a
feature (would this make it an "imprecation period"?)

After that period passes, that's a signal to your API consumers that the
feature will _definitely_ be sticking around and receive long-term support.
But until then, it could be removed without warning at any time; all code that
relies on it should have alternate branches to handle the case where the
feature endpoints pop out of existence.

Pre-1.0, all features are implicitly imprecatory, of course.

------
MichaelGG
What kind of language and library makes creating an XML document is difficult?
I know it's fashionable to hate XML, but seriously, it's a perfectly fine
format, especially for serializing simple documents. The closing tags add some
overhead; big deal.

I'm not even sure why much of a format was needed at all for this scenario.
According to the docs[1], cURL will get a plaintext string, which has to be
sufficient for nearly every implementation needing CNAM data. I'm quite sure I
created a similar CNAM API in 2006: HTTP GET, return 200 OK and a string, or
an HTTP error. Other major vendors' APIs are not difficult to work with,
either (although contracts, VPNs, etc. can be annoying).

One reason there are more complicated APIs is for performance. While HTTP is
simple, pipelining leaves a lot to be desired, and there is a benefit to being
able to just use UDP.

As far as the data returned: I'm not even sure what an application supposed to
do with a relative URI for a number after querying for that number? Or the
price, which is apparently fixed per account? I cannot fathom why something as
complicated as YAML would be needed to deal with such a simple situation: I'd
wager customers asking for that are trying to be trendy or something,
especially as JSON is a subset of YAML.

Not to be too negative -- OpenCNAM looks like the kind of thing telephony
needs: easy, online signup, straightforward pricing.

1: <https://www.opencnam.com/docs/v2/quickstart>

~~~
icebraining
XML is a mediocre format ( _the problem it solves is not hard, and it does not
solve the problem well_ ), but more importantly in this case, it's a format
for serializing _documents_ , and OP was trying to serialize objects.
Obviously, we needs to add some core to perform the translation, though with
any decent library it shouldn't take a full day.

------
tantalor
XML is a mistake. There's rarely a practical advantage to a novel XML schema.
If you're not using a well known schema (e.g., Atom) then omit XML support.

~~~
nrinaudo
I disagree. XML has a huge advantage over JSON: it can be streamed.

When working with JSON, you must load the whole JSON document before you can
start processing it. If the JSON gets big enough, you start having performance
/ memory issues. One might argue that you can just get more powerful hardware,
but that's only half of the equation: you'd solve _your_ problem, but not that
of your clients. Are you going to tell every single one of them that they just
need to spend more money on hardware?

When working with XML, you can choose to store the whole document in memory,
but it's merely convenient, not compulsory. Using a SAX-like parser, you can
stream the whole process and get a much smaller memory footprint.

Having never worked with YAML, I don't know whether the same argument applies.

This is more of a personal issue than an actual one, but another problem I
have with JSON is that once you support it, people are going to demand you
support JSONp - terribly convenient, but a major security hole.

Aside from that, JSON is obviously a great format for small, self-contained
responses that can be consumed by both browsers and heavy applications. It
just doesn't scale well with large responses.

~~~
MichaelGG
Is there any fundamental reason JSON can't be parsed in a streaming fashion?
It seems like you could implement the same kind of one-token-at-a-time parsing
you can do with XML. What am I missing?

JSONp is only a security hole for the client, not the API provider. I suppose
it puts a bit more pressure on the API provider to not get compromised,
though.

~~~
nrinaudo
Well, I _thought_ it wasn't possible to parse JSON in a streaming fashion, but
given the number of annoyed answers I got, that was obviously incorrect.

Let me amend that to the more qualified "the libraries I've used so far don't
allow you to stream JSON". My point is still somewhat valid - most XML
libraries I know offer stream-based parsing out of the box, most JSON
libraries I know don't - but it's not the show stopper I made it out to be,
since it turns out you can, after all, implement your own streamed based
parser.

As for JSONp, you're obviously and entirely right. My point was that, in case
something happens on the client side (through an entirely different security
hole - and let's face it, people who feel comfortable consuming JSONp are
likely to take other insecure shortcuts), I'd much rather not be implicated at
all than have to prove I had nothing to do with it.

------
grimborg
The API should be independent of any serialization format. The serialization
layer should take care of it.

