Skip to content

Instantly share code, notes, and snippets.

@pedro

pedro/notes-apicraft-one-api-to-rule-them-all.md

Created July 30, 2013 18:43
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save pedro/6115623 to your computer and use it in GitHub Desktop.
Save pedro/6115623 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
notes-apicraft-one-api-to-rule-them-all.md

One API to rule them all

An API can be split between:

  • Public
  • Private

Or maybe between consumers:

  • iOS/Android
    • Few webcalls as possible, give a firehose
  • Web apps
    • Give just what they need so it load faster
    • They did at /api/v1/web
  • Others

Worth noticing there are also combinations (eg public iOS api, private web app)

Question: Is this a good idea?!

Notes

  • Background: they had a working API, iOS developers asked for more info, they added to the existing API without much thought and suddenly noticed a performance impact.

  • Organizer wish that he had one API.

  • Question: why more data for iOS?

    • Counterintuitive, but goal is not to give them all that is possible, but everything that they asked for.
    • When there's high latency, six small requests in parallel can take much longer than one big request
    • Doesn't apply just to iOS, same would be the case for customer in Asia for instance.

  • Question: still don't see a difference between Android and Web apps

    • Mobile is trying to get as much stuff in advance so they can cache/provide fast user interaction once they're ready
    • For web apps they didn't want to hit the database as much.

  • It seems like the API split was decided after an internal optimization

    • What if they introduced a caching layer instead?
    • Antipattern: design API after internal/architectural constraints

  • Question: what are the other consumers listed?

  • Proposal: allow clients to decide how much data they want. Then suddenly you have one API that is more flexible.

    • If request includes links, maybe there's a way to inline the representation of these links with the original request.
    • The line between iOS/Android/Others is burry, don't build that into the API

  • Question: do you have predefined media types?

    • Don't render just JSON, define what your resources could look like
    • Web app is built on Backbone, so the models have some knowledge of what they expect to receive from the API.

  • Proposal: version media type, not the path

    • More flexible options, resources should not depend on version. Media types are.
    • How to tell the version which version you're rendering then?
      • Match the response content-type with the request accept header

  • Question: is there an opportunity to expose new resources?

    • For instance, if some resources are grouped by location or type maybe you can expose them as a group?

  • Proposal: build a new service that consumes the public API and composes the big/nested responses that clients like Android could expect

    • "API facade"
    • Do you need something like a batching interface then?

  • What are we optimizing for?

    • User experience
    • Question: But it's still a young company right? You must prioritize ability to change directions and developer productivity!

  • Is the difference between public and private APIs documentation? :}

  • Going back to public/private, is that a good idea in first place?

    • In another session it was discussed to design APIs around user needs
    • Push private APIs as far as you can go until either you're comfortable about making it public or know enough to understand the reasons why you need to keep it private
    • The risk about starting with private and evolving it is that you have more leverage with your own developers
      • There seems to be a pattern with companies unable to publicize their public APIs
      • Argument for making it public ASAP
      • Or for treating the private API more like a public:
        • Avoid adding thousands of new features
        • Expose an API documentation, keep it up to date
    • Why private APIs in first place? Be reasonable about what data you're deciding to make public

  • What about API wrappers/SDKs?

    • Can be bad when it has logic on it. These can easily make assumptions about the API that may change/break with time.
    • Important to notice the difference developers interacting with the API: iOS developers vs web developers.
    • You still own your API. Don't use SDKs to hide API complexities, etc.
    • Seems like there's an agreement that good SDKs are just semantic sugar
    • Question: if that's the case, what about code-generated SDKs? Eg Swagger
      • Some success cases in the room, simple case
      • Write the client you want, see if it can be generated
      • Bigger barrier for contribution: pull requests on the generator, not the client

  • BACK ON THE TOPIC: what's your experience splitting public/private APIs in your company?

    • Considering accepting the "publicized" overhead to make everything public. We tell users they can do all these things into our API.
    • One API, certain users can consume some features, certain users can't
    • What do we gain by splitting it up?
      • Easier authorization/security
      • Supporting different protocols
      • Ability to break the contract
        • But this can be done with versioning

  • Idea: use user agents to allow users different access/capabilities

    • Not considered in the cache invalidation logic! Better avoid
    • It's brilliant for debugging though. Really helps tracking down issues
    • Should not be used for trusted data. Just logging/statistics

Summary:

  • Split documentation, not implementation
  • Use content negotiation, media type for different formats
  • Consensus: have one API to rule them all
    • Make it flexible to account for the different use cases
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment