Atrocious API Architecture (AAA)

Summary

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.

PLANNING

• 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

INTERFACE DESIGN

• 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)

REQUEST DESIGN

• 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

PROJECT MANAGEMENT

• 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

IMPLEMENTATION

• 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

TESTING

• 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)

References

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