2012 Nov 29, christophercotton.com

API Design&Junior ➪ SeniorChristopher Cotton @_cotton for @NashSoftware

The Past

✤ 20+ years Programming

✤ Been QA Tester, Junior Dev, Senior Dev, Technical Lead, Project Lead, Architect, Senior Member of Technical Staff 3 (What?!), CTO, Founder, Consultant and lots of random other jobs

✤ javax.mail http://www.google.com/#q=javax.mail+cotton

The Now

✤ iOS, Android, Ruby on Rails

✤ @NashGameDev

✤ @SpacewardHo

✤ http://handstand.io

✤ Teach Kids Programming (YSI) http://www.fssd.org/index.php?option=com_content&task=view&id=110&Itemid=207

Date

My Version, Not “The Truth”

API stands for?

This does what?

User.find_or_create_by_name("Bob")

API

✤ Contract - documented, agreement, cause/effect

✤ Interface - one service to another

✤ GEM, Library, TCP, HTTP, etc.

✤ Systems Integration

Date

Lonely App

Date

API Here, API There, Everywhere

Date

Current Architecture

Device App

ContentDBScraper Packager FileStorage

Content Server

Blogs/Websites

App.Handstand

Google Analytics Task

Builder

Customer

Builder

Article List

Article Package

Amazon SQS

Market TaskAndroid Market

Config

LogAd List

Ads

AmazonS3

Version 2010/12/31All rights reserved

Handstand

Internal Systems

Date

API - How to Consume

How to use? What would you do?

Date

API - How to Design

Lots of Other Resources

✤ How to design RESTful APIs

✤ CRUD

✤ HTTP API

What is the point?

Who will use it?

✤ Dell Digital Delivery - 10 million machines, more each year to download software

✤ Cyberdog - other developers to implement new components

✤ JavaSoft javax.mail - Developers implementing Services, or sending Email

✤ Handstand - devices retrieving travel magazine

Date

Document, Document, Document

Why Document?

✤ Another programmer will need to know how it works, and trial and error sucks

✤ Test Your API, write a client from your own docs

✤ Keeps your code honest

✤ Becomes a real API when a client is written by someone other than you from your docs

3ULPHU�Y��$3,�6SHFLILFDWLRQ���������� Y�����

&UHDWH�8VHU5(48(67��$XWKHQWLFDWLRQ�QRW�UHTXLUHG�

�3267��DSL�Y��FUHDWHBXVHU

�3$5$0(7(56�

XVHU>HPDLO@ 8VHU¶V�HPDLO� UHTXLUHG

XVHU>SDVVZRUG@ 8VHUV�SDVVZRUG� UHTXLUHG

XVHU>ILUVWBQDPH@ 8VHUV�ILUVW�QDPH� UHTXLUHG

XVHU>ODVWBQDPH@ 8VHUV�ODVW�QDPH� UHTXLUHG

�5(63216(��6HW�&RRNLH�KHDGHU�DQG�-621�SD\ORDG�

�+773���������2.�&RQWHQW�7\SH��DSSOLFDWLRQ�MVRQ��FKDUVHW XWI��6HW�&RRNLH��8 ^XVHUBXLG`��SDWK ���H[SLUHV 6DW�����$XJ���������������*076HW�&RRNLH��7 ^DXWKBWRNHQ`��SDWK ���H[SLUHV 6DW�����$XJ���������������*07�^�����FRGH��������������PVJ����2.�������GDWD���^���������ILUVWBQDPH����^ILUVWBQDPH`�����������ODVWBQDPH����^ODVWBQDPH`�����������XVHUBXLG����^XVHUBXLG`�����``��

(55256�

0HVVDJH���PVJ�� 'HVFULSWLRQ

�HPDLO�PLVVLQJ� 7KH�HPDLO�SDUDPHWHU�ZDV�PLVVLQJ

+DQGVWDQG�&RQILGHQWLDO ��

Find & Reuse Good APIs

✤ Don’t reinvent the wheel

✤ Find another similar, and expand or convert

✤ Learn from bad APIs

Key Aspects

✤ Versioned

✤ Errors - was the request successful? invalid data? server blew up?

✤ Consistent to itself - delete_book, friend_delete

✤ Iteration

✤ Design with a partner or isolation, not large groups

Iteration

✤ High Level APIs

✤ Data Model, Design Objects and Connections

✤ Keep asking, what other actions need to be done? What other data?

✤ Walk through the scenarios

✤ retrieve library, log in, add book, delete book, post comment

Date

Practice, practice, practice

Date

Q & A, Part One

Date

SeniorJunior ➪

✤ Worried about how you look, or what you say

✤ Focused on small parts, misses big picture

✤ Makes changes without understanding repercussions

✤ Not my part

Characteristics of Bad Junior(or bad Senior)

Good Senior Developer(or Good Junior Developer)✤ Says, “I don’t know”

✤ Takes responsibility

✤ Continually Learning

✤ Will “Take one for the team”

✤ Given Any Problem, Can Invent a solution

✤ Can learn needed skills

✤ Goes beyond the basics

Basic Mistakes

Separate Concerns of Code

✤ Putting code unrelated into one group/class

✤ Networking code in the DB code

✤ UI Controller Code, with Table Cell Display Code

✤ Too many lines!

✤ “Wasn’t sure where else to put it” Ask!

Cut & Paste Solutions

✤ Found something on Stack Overflow, paste it in!

✤ The Interweb is not always correct

✤ Take the time to understand what it does, and why

Hard Coded Values

✤ Just don’t do it. Use config, use Class definitions, or Statics

Reinvention, Bad idea

✤ Calendar formatter

✤ Network Library

✤ Search, or ask. Know your domain

Warnings, Errors

✤ Fix warning messages, they are usually there for a reason

✤ If something fails, understand WHY it failed. Interested in making sure it doesn’t happen again

✤ Know where to fix it, document your changes

✤ Example: Cucumber test with TEXTAREA gave an extra ‘\r’

Be sure to test

✤ “I’m sure it must work in all those cases”

✤ Take the time to think about your code

Too Focused on Small Parts

✤ Focus on the most important parts. Don’t know? Ask!

✤ iOS app, focused on getting a particular toolbar exact to the specifications, but those specifications would change

✤ Optimizing before recording data, profiling

How will this change the app?

✤ DB code, using “select statements” and adding in specific fields

✤ Made it work in the short term, impossible to manage in the long term

✤ Change one class, but not really understand how it is used elsewhere

Date

How to Improve

Date

Mentoring

Date

Ask for Feedback, Code Reviews

Date

Read/Learn

Date

Build Tools, APIs, LibrariesDon’t do the same thing over and over

Date

Enjoy the process

Date

What is your.... Q & A, Part Deux