Thursday, September 18, 2014

Atrocious API Architecture (AAA)


Use the following planning, design, implementation and testing pointers to create a terrible API.

Or do the opposite of each recommendation to create an API that rocks.


  • Start building your app before you clearly define your system requirements
  • Do not try to understand your problem domain
  • Do not identify constraints
  • Focus on on individual steps, rather than overall system throughput
  • Do not try to improve efficiency of your biggest constraints (see previous rule)
  • Refer only the articles listed in the References section below


  • Do not use RESTful APIs
  • Use web services and assume your integration partners will not change their APIs
  • Make your API as big as possible
  • Use SOAP or better yet, roll your own request/response protocol
  • Do not apply the Fascade Pattern (expose your implementation details via your API)
  • Do not use default args, varargs, generics or enums
  • Do not version your API (change your API at will without notifying clients)
  • Never use JSON (Use a custom message protocol or at least SOAP)
  • Do not implement rate limiting (allow a single client to hog system resources)
  • Use nonsensical API operation names
  • Use inconsistent API operation names (ex: use both AddProduct and insertClient)


  • Permit non SSL access to various end points
  • Require as much data as possible from your clients to satisfy simple requests
  • Never use interface types for input parameters (use classes)
  • Require generic input parameter types
  • Always use the String type for inputs and outputs
  • Expose access to all internal data fields and methods
  • Use inconsistent parameter ordering (and lots of them!)
  • Force clients to use exceptions for flow control
  • Force client to specify data type of fields in each request
  • Use session based security for long running transactions
  • Do not provide authentication options (do everything in the clear)
  • Do not notify clients when data has been modified (force them to perform bulk reads and compare)
  • Do not filter any of the fields from your database tables
  • Do not allow clients to indicate which fields they want returned in the response
  • Do not return updated_at attribute (make the client hit your API repeatedly for the same data)
  • Do not use HTTP status codes in your response


  • No Agile development (that's a given!)
  • Do not use project management software like Jira, Pivotal Tracker, Rational Team Concert
  • Hold hour-long meetings hourly
  • Micro manage your developers
  • Never allow time for research or prototyping
  • Assume everybody will get everything right the first time and plan accordingly


  • Do not use feature branches
  • Merge all code into the single, master branch
  • Do not tag your commits with a ticket/reference number
  • Do not make your API pluggable
  • Provide the same level of service regardless of business requirements
  • Design such that small specific changes will require lots of system upgrades
  • Always copy and paste code (no code reuse!)
  • Avoid writing modular code
  • Create only mutable objects (avoid stateless design)
  • Avoid functional programming
  • Do not fail early (process as much of the request as possible before you return an error)
  • Use Java (always overload your methods and use subclassing as much as possible)
  • Fail silently when possible
  • Use only global variables
  • Use floating points for monetary values


  • If you do test, do not try to test individual components (which would be nearly impossible, given your needlessly complicated API)
  • Do not write unit tests
  • Do not provide an API test framework for your clients to use
  • Ensure that your tests take so long to run that it is impossible for developers to test their new code before they merge it into the master branch
  • Do not document (and if you do add non-valuable comments like: // This is a loop)


This work is licensed under the Creative Commons Attribution 3.0 Unported License.

No comments:

Post a Comment