@Crell

Senior Architect, Palantir.net
Drupal 8 Web Services Lead
Drupal Representative, PHP-FIG
Advisor, Drupal Association
General busybody

Step 1:

Define your terms

API

Application Programming Interface

Code intended for other code

#1


const STATUS_PUBLISHED = 1;
const STATUS_DRAFT = 0;

function load_articles_by_status($status) {
  // Find articles $ids for $status
  return article_load_multiple($ids);
}

Oops

const MYMODULE_STATUS_PENDING = 3;

const YOURMODULE_STATUS_IN_REVIEW = 3;


function load_articles_by_status($status = '') {
  // Find articles $ids for $status
  return article_load_multiple($ids);
}

node_load_multiple() Druplicon

Drupal 6

// Fetch one node.
function node_load($nid) {
  $record = db_query("SELECT * FROM node WHERE nid=:nid", [':nid' => $nid])
    ->fetchObject();
  $record = load_extra_stuff($record);
  return $record;
}

// Fetch multiple nodes.
function node_load_multiple(array $nids) {
  $records = db_query("SELECT * from node WHERE nid IN (:nids)", [':nids' => $nids])
    ->fetchAll();
  foreach ($records as $record) {
    $loaded[] = load_extra_stuff($record);
  }
  return $loaded;
}

Drupal 7

// Fetch one node.
function node_load($nid) {
  $nodes = node_load_multiple(array($nid));
  return reset($nodes);
}

// Fetch multiple nodes.
function node_load_multiple(array $nids) {
  $records = db_query("SELECT * from node WHERE nid IN (:nids)", [':nids' => $nids])
    ->fetchAll();
  $records = load_extra_stuff($records);
  return $records;
}

Drupal 6 theme system

function theme($hook) {
  // ...
  if (!isset($hooks[$hook])) {
    return;
  }
  // ...
  return $output;
}

Drupal 7 theme system

function theme($hook, $variables = array()) {
  // ...
  if (!isset($hooks[$hook])) {
    if (!isset($candidate)) {
      watchdog('Theme key "{$hook}" not found.');
    }
    return '';
  }
  // ...
  return $output;
}

Good APIs are picky

class InsertQuery extends Query {
  public function fields(array $fields, array $values = []) {
    // ...
  }
  public function preExecute() {
    if (array_intersect($iFields, $defaultFields)) {
      throw new FieldsOverlapException('...');
    }
    // ...
    return TRUE;
  }
}

abstract class FileTransferFTP extends FileTransfer {
   /**
    * Return an object which can implement the FTP protocol.
    *
    * @param string $jail
    * @param array $settings
    * @return FileTransferFTP
    *    The appropriate FileTransferFTP subclass based on available    
    *    options. If the FTP PHP extension is available, use it.
    */
   static function factory($jail, $settings) { }
}

Date.module

/**
 * Getter callback to return date values as datestamp in UTC from the field.
 */
function date_entity_metadata_field_getter($object, array $options,
                                           $name, $obj_type, &$context) { }

No, seriously, WTF?

protected function normalizeCharset($value) {
    switch (mb_detect_encoding($value)) {
    case 'ASCII':
      break;
    case 'UTF-8':
      $value = htmlentities($value, ENT_NOQUOTES);
      $value = html_entity_decode($value, ENT_NOQUOTES, 'UTF-8');
      break;
    case FALSE:
      $value = iconv('Windows-1252', 'UTF-8//TRANSLIT', $value);
      $this->log->warn("Detected Windows-1252 character encoding.");
      break;
    default:
      $this->log->warn("Unrecognized character encoding.");
  }
  return $value;
}

WTF is up with UTF-8? And why is FALSE Windows-1252?

protected function normalizeCharset($value) {
  // mb_detect_encoding() in most situations supports only two character sets,
  // ASCII and UTF-8.  However, it is sadly not unusual for incoming data
  // to be in Windows-1252, aka MS Word. We therefore guess that a
  // false/not-found character set is Windows-1251, and try to convert that
  // to UTF-8.
  // Note: The odds of this breaking on some other character encoding besides
  // those three is rather high.

  // ...
}

switch (mb_detect_encoding($value)) {
  // I have absolutely no idea why UTF-8 strings need to be converted
  // from UTF-8 to UTF-8, but if this code is removed many strings end up
  // failing with invalid multi-byte encoding.
  case 'UTF-8':
    // Convert any characters we possibly can to their HTML encoded entities.
    // If we don't specify a character encoding then this should do at least
    // a passingly decent job of detecting it, or at least doesn't care as much
    // as other APIs do.
    $value = htmlentities($value, ENT_NOQUOTES);
    // Convert those HTML entities back into real characters, but this time
    // insist on UTF-8.  This will at worst convert UTF-8 characters back
    // to UTF-8 and at best convert ISO-8859-1 characters to HTML entities and
    // from HTML entities to UTF-8 characters.
    $value = html_entity_decode($value, ENT_NOQUOTES, 'UTF-8');
    break;


  // ...

  // A False return from mb_detect_encoding() means that it couldn't
  // figure out what the encoding is.  In a standard configuration mb_* only
  // knows about ASCCI and UTF-8, so that's not especially useful. We will
  // make an assumption that anything else is Windows-1252, aka MS Word legacy
  // garbage. If correct, this will convert $value from Windows-1252 to
  // UTF-8, transliterating where necessary rather than just failing.
  case FALSE:
    $value = iconv('Windows-1252', 'UTF-8//TRANSLIT', $value);
    $this->log->warn("Detected Windows-1252 character encoding.");
    break;
}

Interfaces are your friend

interface LogInterface {
  public method log($message, $severity);
}

PSR-3

namespace Psr\Log;

interface LoggerInterface {
  public function log($level, $message, array $context = array());

  public function emergency($message, array $context = array());
  public function alert($message, array $context = array());
  public function critical($message, array $context = array());
  public function error($message, array $context = array());
  public function warning($message, array $context = array());
  public function notice($message, array $context = array());
  public function info($message, array $context = array());
  public function debug($message, array $context = array());
}

In Drupal

interface DrupalCacheInterface {
  function get($cid);
  function getMultiple(&$cids);
  function set($cid, $data, $expire = CACHE_PERMANENT);
  function clear($cid = NULL, $wildcard = FALSE);
  function isEmpty();
}

Explicit interfaces

namespace Psr\Log;

interface LoggerInterface {
  public function log($level, $message, array $context = array());

  public function emergency($message, array $context = array());
  public function alert($message, array $context = array());
  public function critical($message, array $context = array());
  public function error($message, array $context = array());
  public function warning($message, array $context = array());
  public function notice($message, array $context = array());
  public function info($message, array $context = array());
  public function debug($message, array $context = array());
}

Grand Unified Theory of API design

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.

— Martin Golding

You will always know where you live.

In six months, some one will need to do something you never thought of with your code and will not be able to edit it.

Stalk me!

http://www.palantir.net/

http://www.garfieldtech.com/

@Crell

Tell me how I did

https://joind.in/10058

Aphorisms ofAPI Design

@Crell

Step 1:

Define your terms

API

Application Programming Interface

Aphorism

They're not rules

They're more like guidelines

Our Agenda

#1

Asimov's Law

So what?

But aren't booleans 2-state?

Garfield's Law

Drupal 6

SELECT N + 1

Drupal 7

Aphorism #1

#2

Drupal 6 theme system

Drupal 7 theme system

Fail early, fail often

Good APIs are picky

Aphorism #2

#3

Date.module

Lack of comments indicate

What to document

Usage docs

<aside>

</aside>

Aphorism #3

#4

PHPUnit

3 implementations?

Aphorism #4

#5

Leverage existing patterns

Existing patterns

Aphorism #5

#6

Logging

Interfaces are your friend

PSR-3

Caching

In Drupal

PSR-6 (Draft)

Explicit interfaces

Dependency Injection

Separate Logic from Data

Separation of concerns

Aphorism #6

#7

Performance

Aphorism #7

#8

Some numbers

Find existing wheels

Use existing platforms

Use existing standards

Learn from existing wheels

Drupal 8

Ego

Durden's Law

Aphorism #8

Grand Unified Theory of API design

Stalk me!

Tell me how I did

Thanks!

Further reading

Aphorisms of
API Design