5 ms·

I maintain the Twitter API client library for a popular language, and I have a love-hate relationship with the Twitter API. Parts of it are really nice, but som

I maintain the Twitter API client library for a popular language, and I have a love-hate relationship with the Twitter API. Parts of it are really nice, but sometimes I feel like I'm playing whack-a-mole with the documentation. The example responses they provide are correct... except when they aren't. They use heterogenous JSON in their responses (silently replacing string literals with arrays, but only for some responses, etc.). They've added error codes without updating the docs for months on end (which sort of defeats the point of an error code - what use is it if you don't know what the error means?) The only way I'm notified of these changes is when people file bug reports with the library, and I always have to ask them to tell me the exact query that cause the error for them, because they're almost impossible to reproduce otherwise[0], and the API is so inconsistent that I can't try and manually search for similar responses that will cause the error. On the other hand, the Twitter API is a seamless[1] way to interface with an incredibly useful and powerful product, and it's a great source of data. I just wish the developer experience were seamless. [0] e.g. https://github.com/ChimeraCoder/anaconda/issues/82 https://github.com/ChimeraCoder/anaconda/issues/82 [1] Assuming your client library works, but I can't assume that if I'm the one responsible for maintaining it!

MichaelGG 11y ago
Yeah but compared to Facebook and others, Twitter's an absolute dream. Instagram, for instance, had outdated docs, and took to embedding comments in the JSON response (extra fields) telling you certain fields shouldn't be used. Jeez.
- babuskov 11y ago
  I find Facebook docs and APIs to be really good. The only drawback is that they are changing it too often for my liking.
  - blakeyrat 11y ago
    I found Facebook docs and APIs to be really good, until they changed one which completely broke a revenue-generating app and didn't post any notification of the change until a week after it had already gone live. That was a few years back, maybe they're better now. But I doubt it. Both Facebook and Twitter are a complete dream compared to Valve's API for Steam and Team Fortress 2. Working with that is a complete nightmare, if it even provides a fraction of the capability you need (which it almost certainly does not).
    - lnanek2 11y ago
      They are still pretty bad. I'm struggling through a Unity integration right now where we need to use the latest Facebook plugin for Unity, but all their examples and tutorials don't compile with it because they renamed interfaces and the like.
    - Omniusaspirer 11y ago
      SteamRE is what you're looking for, don't even waste your time with Valve API's.
      - blakeyrat 11y ago
        Would be nice if their website gave even an extremely vague idea of what features it has implemented...
        Omniusaspirer 11y ago
        You'll pretty much need to dig into the source, IRC is unlikely to be helpful. Documentation is basically nonexistent as well. With that said...it is what you're looking for and nearly every substantial bit of code built around Steam has been created using that library or the Node variant.
    - mirceal 11y ago
      move fast and break things?
  - tracker1 11y ago
    I worked on FB integration where a feature being used was disabled and the API replaced with a new one between our product freeze and release (actually the old API was closed a week and a half before the replacement was in place). If I was working at a smaller company at the time, our team would have had no way of knowing WTF happened, other than it didn't work. The fact is, even with a large corp to corp relationship, you still can't absolutely rely on API consistency... it's pretty sad, but true... Netflix, Twitter, FB, Google and others have changed/revoked APIs before with minor to significant impace. This is part of the reason why you shouldn't try to make applications designed to scale/adapt for years... design the simplest thing that does the job, and in as modular a way as possible. Avoid "enterprise" patterns as much as possible in favor of the simplest thing that works and is cheap/easy to replace if/when needed. It doesn't mean don't test, consider performance or write good code, just don't rely on it being around, and over-invest in that it likely won't. You never know... a piece of software I once wrote to test our own product turned into its' own product and pieces of it are still in fortune 100 deployments... It's horrible, and was a hack to begin with. It didn't even support half the specification it was designed for (only the parts we needed)... just the same, it got the job done.
  - stephenr 11y ago
    > really good > changing it too often for my liking Does not compute. As others have said, I have had the misfortune of working on a project that used the FB API and relying on a feature that just inexplicably stopped working right around the time we were supposed to go live. I was already personally uninterested in FB when this happened, but it gave me concrete belief of two very simple realisations: - Tying your success to the whims of a third party company's developers is going to end in tears - A motto like "Move fast and break stuff" is just an attempt to re-brand their fucking terrible development practices in a way that junior developers will treat as a positive thing.
- danudey 11y ago
  Someone I know designed a server-side REST API framework which would respond to browser requests to /foo/bar/ with auto-generated HTML documentation for /foo/bar/. Thus, if you were having an issue with a specific call, you could just copy/paste the URL into your browser and see what you were doing wrong. IIRC he also had support for making requests/responses in your browser to test, but that could just be an idea that never got implemented.
  - sk5t 11y ago
    Re. in-browser requests, Cloudant's documentation does that, alongside instructions for curl.
jamescampbell 11y ago
I've found PAWS to be indispensable for investigating twitter and other apis in a visual way. It allows you to parse out and in the parameters you are setting and seeing. Saved me a lot of headache trying to break out the nested JSON mess. Not sure I can post a link here but it is Paws 2 in the app store.

MichaelGG 11y ago

Yeah but compared to Facebook and others, Twitter's an absolute dream. Instagram, for instance, had outdated docs, and took to embedding comments in the JSON response (extra fields) telling you certain fields shouldn't be used. Jeez.

babuskov 11y ago
I find Facebook docs and APIs to be really good. The only drawback is that they are changing it too often for my liking.
- blakeyrat 11y ago
  I found Facebook docs and APIs to be really good, until they changed one which completely broke a revenue-generating app and didn't post any notification of the change until a week after it had already gone live. That was a few years back, maybe they're better now. But I doubt it. Both Facebook and Twitter are a complete dream compared to Valve's API for Steam and Team Fortress 2. Working with that is a complete nightmare, if it even provides a fraction of the capability you need (which it almost certainly does not).
  - lnanek2 11y ago
    They are still pretty bad. I'm struggling through a Unity integration right now where we need to use the latest Facebook plugin for Unity, but all their examples and tutorials don't compile with it because they renamed interfaces and the like.
  - Omniusaspirer 11y ago
    SteamRE is what you're looking for, don't even waste your time with Valve API's.
    - blakeyrat 11y ago
      Would be nice if their website gave even an extremely vague idea of what features it has implemented...
      - Omniusaspirer 11y ago
        You'll pretty much need to dig into the source, IRC is unlikely to be helpful. Documentation is basically nonexistent as well. With that said...it is what you're looking for and nearly every substantial bit of code built around Steam has been created using that library or the Node variant.
  - mirceal 11y ago
    move fast and break things?
- tracker1 11y ago
  I worked on FB integration where a feature being used was disabled and the API replaced with a new one between our product freeze and release (actually the old API was closed a week and a half before the replacement was in place). If I was working at a smaller company at the time, our team would have had no way of knowing WTF happened, other than it didn't work. The fact is, even with a large corp to corp relationship, you still can't absolutely rely on API consistency... it's pretty sad, but true... Netflix, Twitter, FB, Google and others have changed/revoked APIs before with minor to significant impace. This is part of the reason why you shouldn't try to make applications designed to scale/adapt for years... design the simplest thing that does the job, and in as modular a way as possible. Avoid "enterprise" patterns as much as possible in favor of the simplest thing that works and is cheap/easy to replace if/when needed. It doesn't mean don't test, consider performance or write good code, just don't rely on it being around, and over-invest in that it likely won't. You never know... a piece of software I once wrote to test our own product turned into its' own product and pieces of it are still in fortune 100 deployments... It's horrible, and was a hack to begin with. It didn't even support half the specification it was designed for (only the parts we needed)... just the same, it got the job done.
- stephenr 11y ago
  > really good > changing it too often for my liking Does not compute. As others have said, I have had the misfortune of working on a project that used the FB API and relying on a feature that just inexplicably stopped working right around the time we were supposed to go live. I was already personally uninterested in FB when this happened, but it gave me concrete belief of two very simple realisations: - Tying your success to the whims of a third party company's developers is going to end in tears - A motto like "Move fast and break stuff" is just an attempt to re-brand their fucking terrible development practices in a way that junior developers will treat as a positive thing.
danudey 11y ago
Someone I know designed a server-side REST API framework which would respond to browser requests to /foo/bar/ with auto-generated HTML documentation for /foo/bar/. Thus, if you were having an issue with a specific call, you could just copy/paste the URL into your browser and see what you were doing wrong. IIRC he also had support for making requests/responses in your browser to test, but that could just be an idea that never got implemented.
- sk5t 11y ago
  Re. in-browser requests, Cloudant's documentation does that, alongside instructions for curl.

jamescampbell 11y ago

I've found PAWS to be indispensable for investigating twitter and other apis in a visual way. It allows you to parse out and in the parameters you are setting and seeing. Saved me a lot of headache trying to break out the nested JSON mess. Not sure I can post a link here but it is Paws 2 in the app store.