SlideShare uma empresa Scribd logo
1 de 29
Baixar para ler offline
Practices	
  and	
  Tools	
  for	
  Building	
  Better	
  APIs

	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  @PeterHendriks80,	
  +PeterHendriks
Objectives	
  of	
  this	
  talk
• API	
  from	
  a	
  Java	
  app	
  developer	
  perspective	
  
!

•
•
•
•

Why	
  API	
  is	
  important	
  
What	
  makes	
  a	
  better	
  API	
  
Practical	
  tips	
  and	
  tools	
  
Measuring	
  your	
  existing	
  codebase
Some	
  API	
  terminology
• API	
  Consumer:	
  code	
  that	
  uses	
  API	
  
• API:	
  the	
  interface	
  
• API	
  Implementer:	
  code	
  that	
  implements	
  API
API	
  
Consumer

API

API	
  
Implementer

Data	
  Access	
  Object

JDBC

Database	
  Driver
We	
  are	
  using	
  a	
  lot	
  of	
  API
Bazillion	
  Open	
  
Source	
  Web	
  
Framework	
  API’s	
  
Spring:	
  27	
  API’s
Java	
  EE:	
  37	
  API’s
Java	
  SE:	
  45	
  API’s

Enterprise	
  Service	
  
API’s
Public	
  Service	
  API’s
Cloud	
  API’s
Middleware	
  API’s
We	
  are	
  building	
  more	
  of	
  them,	
  too
• API	
  is	
  key	
  to	
  a	
  succesful	
  module	
  design	
  
– Essential	
  for	
  agile	
  teams	
  at	
  scale
Customer	
  
Front-­‐End

Warehouse	
  
Front-­‐End

Order	
  
Management
Shared	
  code
Distance	
  to	
  API	
  implementation	
  is	
  increasing
• API	
  quality	
  increasing	
  important	
  when	
  
implementation	
  becomes	
  a	
  black	
  box

Same	
  
team

Different	
  
team

Open	
  
source

Binary	
  
only

Other	
  
datacenter
The	
  API	
  we	
  use	
  shapes	
  our	
  code
• Most	
  code	
  we	
  write	
  calls	
  an	
  API	
  
• Code	
  that	
  calls	
  an	
  API	
  is	
  shaped	
  to	
  fit	
  the	
  API	
  
• Therefore,	
  APIs	
  determine	
  the	
  shape	
  of	
  
application	
  code	
  
– In	
  some	
  ways,	
  even	
  more	
  impactful	
  than	
  high	
  level	
  
design,	
  test	
  driven	
  development	
  or	
  code	
  
craftsmanship
!

http://docs.oracle.com/javaee/1.4/tutorial/examples/jaxp/xslt/samples/
TransformationApp04.java	
  

!

public	
  class	
  TransformationApp04	
  {	
  
	
  	
  	
  	
  public	
  static	
  void	
  main(String[]	
  argv)	
  {	
  
	
  	
  	
  	
  	
  	
  	
  	
  if	
  (argv.length	
  !=	
  1)	
  {	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  System.err.println("Usage:	
  java	
  TransformationApp	
  filename");	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  System.exit(1);	
  
	
  	
  	
  	
  	
  	
  	
  	
  }	
  

!

	
  	
  	
  	
  	
  	
  	
  	
  //	
  Create	
  the	
  sax	
  "parser".	
  
	
  	
  	
  	
  	
  	
  	
  	
  AddressBookReader02	
  saxReader	
  =	
  new	
  AddressBookReader02();	
  
var	
  json_data	
  =	
  JSON.stringify(obj);
	
  	
  	
  	
  	
  	
  	
  	
  try	
  {	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  File	
  f	
  =	
  new	
  File(argv[0]);	
  

!
!

	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  //	
  Use	
  a	
  Transformer	
  for	
  output	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  TransformerFactory	
  tFactory	
  =	
  TransformerFactory.newInstance();	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  Transformer	
  transformer	
  =	
  tFactory.newTransformer();	
  

!

	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  //	
  Use	
  the	
  parser	
  as	
  a	
  SAX	
  source	
  for	
  input	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  FileReader	
  fr	
  =	
  new	
  FileReader(f);	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  BufferedReader	
  br	
  =	
  new	
  BufferedReader(fr);	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  InputSource	
  inputSource	
  =	
  new	
  InputSource(fr);	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  SAXSource	
  source	
  =	
  new	
  SAXSource(saxReader,	
  inputSource);	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  StreamResult	
  result	
  =	
  new	
  StreamResult(System.out);	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  transformer.transform(source,	
  result);	
  
	
  	
  	
  	
  	
  	
  	
  	
  }	
  catch	
  (TransformerConfigurationException	
  tce)	
  {	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  //	
  Error	
  generated	
  by	
  the	
  parser	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  System.out.println("n**	
  Transformer	
  Factory	
  error");	
  
	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  System.out.println("	
  	
  	
  "	
  +	
  tce.getMessage());	
  

!
What	
  makes	
  a	
  better	
  API
API	
  Quality:	
  Value
• Value	
  =	
  benefits	
  -­‐	
  costs	
  
• Benefits	
  
– Features	
  
– Data	
  
– ...	
  

• Costs	
  
–
–
–
–

License/pay	
  per	
  use	
  
Performance/footprint	
  
Security	
  
…
API	
  Quality:	
  Usability
• API	
  Design	
  ==	
  Human	
  Interface	
  design	
  
– Although	
  API	
  is	
  for	
  machine/machine	
  interaction,	
  
APIs	
  need	
  to	
  be	
  understood	
  by	
  programmers	
  to	
  
write	
  the	
  code	
  
– Programmers	
  are	
  humans
API	
  is	
  not	
  just	
  about	
  capability	
  and	
  structural	
  
design,	
  but	
  also	
  about	
  human	
  understanding
A	
  simple	
  model	
  for	
  API	
  Usability
Generic	
  usability	
  model	
  by	
  Ben	
  Shneiderman:
Learnability:	
  How	
  easy	
  is	
  it	
  to	
  accomplish	
  basic	
  
tasks	
  the	
  first	
  time?	
  
Efficiency:	
  Once	
  users	
  learned	
  the	
  design,	
  how	
  
quickly	
  can	
  they	
  perform	
  tasks?	
  
Memorability:	
  When	
  users	
  return	
  after	
  a	
  while,	
  
how	
  easily	
  can	
  they	
  re-­‐establish	
  proficiency?	
  
Errors:	
  How	
  many	
  errors	
  do	
  users	
  make,	
  how	
  
severe	
  are	
  these	
  errors,	
  and	
  how	
  easily	
  can	
  they	
  
recover	
  from	
  the	
  errors?	
  
Satisfaction:	
  How	
  pleasant	
  is	
  it	
  to	
  use	
  the	
  design?
API	
  Quality:	
  stability
Able	
  to	
  enhance/grow	
  implementation	
  without	
  
breaking	
  existing	
  consumer	
  code
Google	
  AppEngine	
  release	
  notes:	
  
Version	
  1.7.5	
  -­‐	
  February	
  13,	
  2013	
  
The	
  Conversion	
  API,	
  which	
  was	
  decommissioned	
  last	
  release,	
  has	
  been	
  
removed	
  from	
  the	
  SDK.	
  In	
  a	
  future	
  release,	
  the	
  API	
  will	
  be	
  removed	
  from	
  the	
  
runtime	
  and	
  applications	
  that	
  attempt	
  to	
  use	
  it	
  may	
  stop	
  working.	
  Applications	
  
in	
  production	
  that	
  import	
  the	
  library	
  should	
  be	
  fixed	
  as	
  soon	
  as	
  possible.	
  
Version	
  1.8.4	
  -­‐	
  September	
  9,	
  2013	
  
The	
  Conversion	
  API,	
  a	
  decommissioned	
  feature,	
  has	
  been	
  removed	
  from	
  the	
  
SDK.	
  In	
  the	
  next	
  release,	
  the	
  API	
  will	
  be	
  removed	
  from	
  the	
  runtime	
  and	
  any	
  
attempt	
  to	
  import	
  the	
  API	
  will	
  raise	
  an	
  exception.	
  
Version	
  1.8.5	
  -­‐	
  September	
  25,	
  2013	
  
The	
  Conversion	
  API,	
  a	
  decommissioned	
  feature,	
  has	
  been	
  removed	
  from	
  the	
  
runtime.	
  Applications	
  in	
  production	
  that	
  import	
  the	
  API	
  should	
  be	
  fixed	
  as	
  
soon	
  as	
  possible.
API	
  Quality:	
  A	
  hierarchy	
  of	
  needs
Stability	
  only	
  matters	
  when	
  
API	
  is	
  valuable	
  and	
  usable	
  

Stable

Usable

Valuable
Building	
  Better	
  APIs
API	
  Design:	
  start	
  with	
  examples
• Examples	
  most	
  important	
  in	
  API	
  
documentation	
  
– Concrete	
  use	
  case,	
  usability	
  check	
  

• Make	
  examples	
  exemplary	
  
– Example	
  code	
  will	
  be	
  copy-­‐pasted	
  

• Create	
  a	
  cheat	
  sheet	
  
– Improves	
  learnability	
  
– Shows	
  design	
  issues
API	
  Design:	
  multiple	
  perspectives
Names,	
  Completeness,	
  
Grouping

UML:

public	
  class	
  Document	
  {	
  

!
!

	
  	
  private	
  List<Page>	
  pages	
  =	
  new	
  ArrayList<>();	
  

Impl:

Consumer:

	
  	
  public	
  Page	
  addPage()	
  {	
  
	
  	
  	
  	
  Page	
  page	
  =	
  new	
  Page();	
  
	
  	
  	
  	
  pages.add(page);	
  
	
  	
  	
  	
  page.setPageNumber(pages.size());	
  
	
  	
  	
  	
  return	
  page;	
  
	
  	
  }	
  
	
  	
  	
  
	
  	
  public	
  void	
  report()	
  {...}	
  
}

Page	
  page	
  =	
  document.addPage();	
  
page.setContents("Once	
  upon	
  a	
  time...");

Can	
  it	
  be	
  built?

Is	
  it	
  usable?
API	
  practice:	
  Keep	
  it	
  simple
• Try	
  to	
  stick	
  to	
  just	
  methods	
  and	
  constructors	
  
– Factories,	
  Delegates,	
  etc.	
  not	
  always	
  necessary	
  
!

• “When	
  in	
  doubt	
  leave	
  it	
  out”	
  
– Less	
  classes,	
  methods	
  
– Less	
  parameters,	
  return	
  values

Josh	
  Bloch,	
  Java	
  API	
  guru
API	
  practice:	
  avoid	
  verbose	
  constructs
• Constructs	
  that	
  create	
  verbose	
  consumer	
  code	
  
– Extending	
  class/implementing	
  interface	
  
– Checked	
  exception	
  
– Required	
  casting	
  
– Required	
  generic	
  type	
  
– Required	
  if,	
  for,	
  while,	
  try/finally	
  
– Required	
  synchronization/locking	
  
– Hard	
  coded	
  parameter	
  value
Example:	
  doing	
  some	
  loggin’
• Demo:	
  different	
  styles	
  of	
  logging	
  API
Why	
  Lambdas	
  are	
  so	
  much	
  better	
  than	
  inner	
  
classes
• Inner	
  classes,	
  or	
  extending	
  existing	
  classes	
  
often	
  needed	
  
– Resource	
  handling	
  
– Looping/visiting	
  collections	
  
– Event	
  handling	
  

• Lambdas	
  provide	
  a	
  much	
  more	
  usable	
  
construct	
  
– Shorter,	
  safer,	
  better	
  footprint/performance
Example:	
  Lambda	
  benefits
• Demo:	
  Netbeans	
  example
API	
  practice:	
  fail	
  fast,	
  fail	
  hard
• Fail	
  immediately	
  on	
  wrong	
  input	
  
• Limit	
  the	
  use	
  of	
  null	
  as	
  valid	
  input/output
public	
  void	
  save(String	
  filename)	
  {	
  
	
  	
  if	
  (filename	
  ==	
  null)	
  {	
  
	
  	
  	
  	
  return;	
  //	
  bad	
  api:	
  error	
  is	
  ignored!	
  
	
  	
  }	
  
	
  	
  ...	
  //	
  save	
  happens	
  here	
  
}

Better

public	
  void	
  save(String	
  filename)	
  {	
  
	
  	
  Objects.requireNonNull(filename);	
  
	
  	
  //	
  Throws	
  NPE	
  immediately	
  
	
  	
  ...	
  //	
  save	
  happens	
  here	
  
}
API	
  Tool:	
  checking	
  for	
  null
• Tool:	
  FindBugs,	
  a	
  static	
  code	
  analyzer	
  
– Reports	
  errors	
  at	
  compile-­‐time	
  

• Annotations	
  for	
  Software	
  Defect	
  Detection

(JSR	
  305:	
  Dormant)	
  
– @Nonnull:	
  may	
  never	
  be	
  null	
  
– @CheckForNull:	
  should	
  always	
  be	
  checked	
  before	
  
dereferenced	
  
– @Nullable:	
  caller	
  decides	
  if	
  null	
  check	
  is	
  needed	
  

• Java	
  8	
  will	
  add	
  more	
  annotation	
  options	
  for	
  tools
FindBugs	
  demo	
  in	
  Eclipse
Finding	
  API	
  problems	
  in	
  your	
  code
• People	
  
– Team	
  knowledge	
  
– Policy,	
  “best	
  practices”,	
  conventions	
  
– Elaborate	
  explanation,	
  “hard	
  to	
  do”	
  
– Defect	
  lists/exceptions/stack	
  traces	
  

• Tools	
  
– Finding	
  most	
  used	
  API:	
  Dependency	
  Structure	
  
Matrix	
  (DSM)
How	
  a	
  Dependency	
  Structure	
  Matrix	
  works
Classes/Packages

Document
Document

2

TextBlock

-­‐

Page

Page

TextBlock

-­‐
10

#	
  of	
  direct	
  dependencies	
  from	
  
Document	
  to	
  Page

-­‐
Demo:	
  SonarQube	
  DSM
API	
  design	
  cheat	
  sheet
API	
  matters:	
  
Reuse	
  3rd	
  party	
  
Modular	
  design	
  
Distance	
  to	
  impl.
A	
  Better	
  API	
  is:	
  
1. Valuable	
  	
  
2. Usable	
  	
  
3. Stable
API	
  usability:	
  
• Learnability	
  
• Efficiency	
  
• Memorability	
  
• Error	
  rate	
  
• Satisfaction

API	
  Design	
  Perspectives:	
  
UML:	
  names,	
  completeness,	
  grouping	
  
Implementation:	
  can	
  it	
  be	
  built	
  
API	
  usage:	
  how	
  usable	
  is	
  it	
  
Examples	
  First
JSR	
  305/FindBugs:	
  
@Nonnull:	
  may	
  never	
  be	
  null	
  
@CheckForNull:	
  always	
  check	
  
@Nullable:	
  caller	
  decides	
  null	
  check
DSM:	
  finding	
  most	
  used	
  API
Document
Document

2

TextBlock

-­‐

Page

Page

TextBlock

-­‐
10

	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  @PeterHendriks80,	
  +PeterHendriks

-­‐

API	
  Design	
  practices:	
  
When	
  in	
  doubt	
  leave	
  it	
  out	
  
Limit	
  API	
  consumer	
  code	
  to	
  a	
  minimum	
  
• Extending	
  class/interface	
  
• Checked	
  Exception	
  
• Required	
  casting	
  
• Required	
  Generic	
  Type	
  
• Hard	
  coded	
  parameter	
  value	
  
• Required	
  if,	
  for,	
  while,	
  try	
  
• Required	
  synchronization/locking	
  

!

Be	
  predictable	
  and	
  obvious	
  
• Methods	
  calleable	
  in	
  any	
  order	
  
• Constructor	
  should	
  only	
  construct	
  
• Don’t	
  have	
  surprising	
  side	
  effects	
  
• Limit	
  null	
  as	
  input/output	
  
• Fail	
  fast,	
  fail	
  hard

Eval!

Mais conteúdo relacionado

Mais procurados

Introduction to Apache Pig
Introduction to Apache PigIntroduction to Apache Pig
Introduction to Apache PigJason Shao
 
Devops at Netflix (re:Invent)
Devops at Netflix (re:Invent)Devops at Netflix (re:Invent)
Devops at Netflix (re:Invent)Jeremy Edberg
 
Scaling Push Messaging for Millions of Netflix Devices
Scaling Push Messaging for Millions of Netflix DevicesScaling Push Messaging for Millions of Netflix Devices
Scaling Push Messaging for Millions of Netflix DevicesSusheel Aroskar
 
JavaScript - Chapter 1 - Problem Solving
 JavaScript - Chapter 1 - Problem Solving JavaScript - Chapter 1 - Problem Solving
JavaScript - Chapter 1 - Problem SolvingWebStackAcademy
 
Scalability, Availability & Stability Patterns
Scalability, Availability & Stability PatternsScalability, Availability & Stability Patterns
Scalability, Availability & Stability PatternsJonas Bonér
 
Introduction to data flow management using apache nifi
Introduction to data flow management using apache nifiIntroduction to data flow management using apache nifi
Introduction to data flow management using apache nifiAnshuman Ghosh
 
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQL
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQLSteps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQL
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQLconfluent
 
Jitney, Kafka at Airbnb
Jitney, Kafka at AirbnbJitney, Kafka at Airbnb
Jitney, Kafka at Airbnbalexismidon
 
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020Altinity Ltd
 
Troubleshooting Kerberos in Hadoop: Taming the Beast
Troubleshooting Kerberos in Hadoop: Taming the BeastTroubleshooting Kerberos in Hadoop: Taming the Beast
Troubleshooting Kerberos in Hadoop: Taming the BeastDataWorks Summit
 
Why you should care about data layout in the file system with Cheng Lian and ...
Why you should care about data layout in the file system with Cheng Lian and ...Why you should care about data layout in the file system with Cheng Lian and ...
Why you should care about data layout in the file system with Cheng Lian and ...Databricks
 
Improving Apache Spark by Taking Advantage of Disaggregated Architecture
Improving Apache Spark by Taking Advantage of Disaggregated ArchitectureImproving Apache Spark by Taking Advantage of Disaggregated Architecture
Improving Apache Spark by Taking Advantage of Disaggregated ArchitectureDatabricks
 
Bootstrap for Beginners
Bootstrap for BeginnersBootstrap for Beginners
Bootstrap for BeginnersD'arce Hess
 
BASH Variables Part 1: Basic Interpolation
BASH Variables Part 1: Basic InterpolationBASH Variables Part 1: Basic Interpolation
BASH Variables Part 1: Basic InterpolationWorkhorse Computing
 
Logging Application Behavior to MongoDB
Logging Application Behavior to MongoDBLogging Application Behavior to MongoDB
Logging Application Behavior to MongoDBRobert Stewart
 
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das Databricks
 
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...Simplilearn
 

Mais procurados (20)

HBase in Practice
HBase in Practice HBase in Practice
HBase in Practice
 
Introduction to Apache Pig
Introduction to Apache PigIntroduction to Apache Pig
Introduction to Apache Pig
 
Devops at Netflix (re:Invent)
Devops at Netflix (re:Invent)Devops at Netflix (re:Invent)
Devops at Netflix (re:Invent)
 
Scaling Push Messaging for Millions of Netflix Devices
Scaling Push Messaging for Millions of Netflix DevicesScaling Push Messaging for Millions of Netflix Devices
Scaling Push Messaging for Millions of Netflix Devices
 
Laravel Lab
Laravel LabLaravel Lab
Laravel Lab
 
Technical tips for secure Apache Hadoop cluster #ApacheConAsia #ApacheCon
Technical tips for secure Apache Hadoop cluster #ApacheConAsia #ApacheConTechnical tips for secure Apache Hadoop cluster #ApacheConAsia #ApacheCon
Technical tips for secure Apache Hadoop cluster #ApacheConAsia #ApacheCon
 
JavaScript - Chapter 1 - Problem Solving
 JavaScript - Chapter 1 - Problem Solving JavaScript - Chapter 1 - Problem Solving
JavaScript - Chapter 1 - Problem Solving
 
Scalability, Availability & Stability Patterns
Scalability, Availability & Stability PatternsScalability, Availability & Stability Patterns
Scalability, Availability & Stability Patterns
 
Introduction to data flow management using apache nifi
Introduction to data flow management using apache nifiIntroduction to data flow management using apache nifi
Introduction to data flow management using apache nifi
 
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQL
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQLSteps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQL
Steps to Building a Streaming ETL Pipeline with Apache Kafka® and KSQL
 
Jitney, Kafka at Airbnb
Jitney, Kafka at AirbnbJitney, Kafka at Airbnb
Jitney, Kafka at Airbnb
 
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020
MindsDB - Machine Learning in ClickHouse - SF ClickHouse Meetup September 2020
 
Troubleshooting Kerberos in Hadoop: Taming the Beast
Troubleshooting Kerberos in Hadoop: Taming the BeastTroubleshooting Kerberos in Hadoop: Taming the Beast
Troubleshooting Kerberos in Hadoop: Taming the Beast
 
Why you should care about data layout in the file system with Cheng Lian and ...
Why you should care about data layout in the file system with Cheng Lian and ...Why you should care about data layout in the file system with Cheng Lian and ...
Why you should care about data layout in the file system with Cheng Lian and ...
 
Improving Apache Spark by Taking Advantage of Disaggregated Architecture
Improving Apache Spark by Taking Advantage of Disaggregated ArchitectureImproving Apache Spark by Taking Advantage of Disaggregated Architecture
Improving Apache Spark by Taking Advantage of Disaggregated Architecture
 
Bootstrap for Beginners
Bootstrap for BeginnersBootstrap for Beginners
Bootstrap for Beginners
 
BASH Variables Part 1: Basic Interpolation
BASH Variables Part 1: Basic InterpolationBASH Variables Part 1: Basic Interpolation
BASH Variables Part 1: Basic Interpolation
 
Logging Application Behavior to MongoDB
Logging Application Behavior to MongoDBLogging Application Behavior to MongoDB
Logging Application Behavior to MongoDB
 
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das
Apache Spark 2.0: A Deep Dive Into Structured Streaming - by Tathagata Das
 
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...
What Is Apache Spark? | Introduction To Apache Spark | Apache Spark Tutorial ...
 

Semelhante a Practices and tools for building better API (JFall 2013)

Practices and Tools for Building Better APIs
Practices and Tools for Building Better APIsPractices and Tools for Building Better APIs
Practices and Tools for Building Better APIsPeter Hendriks
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)Tom Johnson
 
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017Amazon Web Services
 
Alfresco Development Framework Basic
Alfresco Development Framework BasicAlfresco Development Framework Basic
Alfresco Development Framework BasicMario Romano
 
Infinum Android Talks #02 - How to write an annotation processor in Android
Infinum Android Talks #02 - How to write an annotation processor in AndroidInfinum Android Talks #02 - How to write an annotation processor in Android
Infinum Android Talks #02 - How to write an annotation processor in AndroidInfinum
 
REST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in CodeigniterREST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in CodeigniterSachin G Kulkarni
 
Review Paper on Online Java Compiler
Review Paper on Online Java CompilerReview Paper on Online Java Compiler
Review Paper on Online Java CompilerIRJET Journal
 
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...Charles Beyer
 
Schema-First API Design
Schema-First API DesignSchema-First API Design
Schema-First API DesignYos Riady
 
API First Workflow: How could we have better API Docs through DevOps pipeline
API First Workflow: How could we have better API Docs through DevOps pipelineAPI First Workflow: How could we have better API Docs through DevOps pipeline
API First Workflow: How could we have better API Docs through DevOps pipelinePronovix
 
Managing the Continuous Delivery of Code to AWS Lambda
Managing the Continuous Delivery of Code to AWS LambdaManaging the Continuous Delivery of Code to AWS Lambda
Managing the Continuous Delivery of Code to AWS LambdaAmazon Web Services
 
Vinay Kumar [InfluxData] | InfluxDB API Overview | InfluxDays 2022
Vinay Kumar [InfluxData] | InfluxDB API Overview  | InfluxDays 2022Vinay Kumar [InfluxData] | InfluxDB API Overview  | InfluxDays 2022
Vinay Kumar [InfluxData] | InfluxDB API Overview | InfluxDays 2022InfluxData
 
Build Great Networked APIs with Swift, OpenAPI, and gRPC
Build Great Networked APIs with Swift, OpenAPI, and gRPCBuild Great Networked APIs with Swift, OpenAPI, and gRPC
Build Great Networked APIs with Swift, OpenAPI, and gRPCTim Burks
 
How to build a JavaScript toolkit
How to build a JavaScript toolkitHow to build a JavaScript toolkit
How to build a JavaScript toolkitMichael Nelson
 
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
 
Application Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldApplication Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldAmazon Web Services
 
2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open StandardsAPIsecure_ Official
 
API workshop by AWS and 3scale
API workshop by AWS and 3scaleAPI workshop by AWS and 3scale
API workshop by AWS and 3scale3scale
 
Application Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldApplication Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldAmazon Web Services
 

Semelhante a Practices and tools for building better API (JFall 2013) (20)

Practices and Tools for Building Better APIs
Practices and Tools for Building Better APIsPractices and Tools for Building Better APIs
Practices and Tools for Building Better APIs
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)
 
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017
Building CI/CD Pipelines for Serverless Applications - SRV302 - re:Invent 2017
 
Alfresco Development Framework Basic
Alfresco Development Framework BasicAlfresco Development Framework Basic
Alfresco Development Framework Basic
 
Infinum Android Talks #02 - How to write an annotation processor in Android
Infinum Android Talks #02 - How to write an annotation processor in AndroidInfinum Android Talks #02 - How to write an annotation processor in Android
Infinum Android Talks #02 - How to write an annotation processor in Android
 
REST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in CodeigniterREST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in Codeigniter
 
Review Paper on Online Java Compiler
Review Paper on Online Java CompilerReview Paper on Online Java Compiler
Review Paper on Online Java Compiler
 
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...
Hyperion EPM APIs - Added value from HFM, Workspace, FDM, Smartview, and Shar...
 
Schema-First API Design
Schema-First API DesignSchema-First API Design
Schema-First API Design
 
API First Workflow: How could we have better API Docs through DevOps pipeline
API First Workflow: How could we have better API Docs through DevOps pipelineAPI First Workflow: How could we have better API Docs through DevOps pipeline
API First Workflow: How could we have better API Docs through DevOps pipeline
 
Managing the Continuous Delivery of Code to AWS Lambda
Managing the Continuous Delivery of Code to AWS LambdaManaging the Continuous Delivery of Code to AWS Lambda
Managing the Continuous Delivery of Code to AWS Lambda
 
Vinay Kumar [InfluxData] | InfluxDB API Overview | InfluxDays 2022
Vinay Kumar [InfluxData] | InfluxDB API Overview  | InfluxDays 2022Vinay Kumar [InfluxData] | InfluxDB API Overview  | InfluxDays 2022
Vinay Kumar [InfluxData] | InfluxDB API Overview | InfluxDays 2022
 
Build Great Networked APIs with Swift, OpenAPI, and gRPC
Build Great Networked APIs with Swift, OpenAPI, and gRPCBuild Great Networked APIs with Swift, OpenAPI, and gRPC
Build Great Networked APIs with Swift, OpenAPI, and gRPC
 
How to build a JavaScript toolkit
How to build a JavaScript toolkitHow to build a JavaScript toolkit
How to build a JavaScript toolkit
 
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...
 
How to design effective APIs
How to design effective APIsHow to design effective APIs
How to design effective APIs
 
Application Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldApplication Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless World
 
2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards2022 APIsecure_Securing APIs with Open Standards
2022 APIsecure_Securing APIs with Open Standards
 
API workshop by AWS and 3scale
API workshop by AWS and 3scaleAPI workshop by AWS and 3scale
API workshop by AWS and 3scale
 
Application Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless WorldApplication Lifecycle Management in a Serverless World
Application Lifecycle Management in a Serverless World
 

Último

Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaborationbruanjhuli
 
Computer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsComputer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsSeth Reyes
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfinfogdgmi
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioChristian Posta
 
Digital magic. A small project for controlling smart light bulbs.
Digital magic. A small project for controlling smart light bulbs.Digital magic. A small project for controlling smart light bulbs.
Digital magic. A small project for controlling smart light bulbs.francesco barbera
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureEric D. Schabell
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Websitedgelyza
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfDaniel Santiago Silva Capera
 
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationIES VE
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...DianaGray10
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfDianaGray10
 
Babel Compiler - Transforming JavaScript for All Browsers.pptx
Babel Compiler - Transforming JavaScript for All Browsers.pptxBabel Compiler - Transforming JavaScript for All Browsers.pptx
Babel Compiler - Transforming JavaScript for All Browsers.pptxYounusS2
 
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UbiTrack UK
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IES VE
 
Do we need a new standard for visualizing the invisible?
Do we need a new standard for visualizing the invisible?Do we need a new standard for visualizing the invisible?
Do we need a new standard for visualizing the invisible?SANGHEE SHIN
 
Cloud Revolution: Exploring the New Wave of Serverless Spatial Data
Cloud Revolution: Exploring the New Wave of Serverless Spatial DataCloud Revolution: Exploring the New Wave of Serverless Spatial Data
Cloud Revolution: Exploring the New Wave of Serverless Spatial DataSafe Software
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8DianaGray10
 

Último (20)

Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
 
Computer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and HazardsComputer 10: Lesson 10 - Online Crimes and Hazards
Computer 10: Lesson 10 - Online Crimes and Hazards
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdf
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and Istio
 
Digital magic. A small project for controlling smart light bulbs.
Digital magic. A small project for controlling smart light bulbs.Digital magic. A small project for controlling smart light bulbs.
Digital magic. A small project for controlling smart light bulbs.
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability Adventure
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Website
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
 
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
 
Babel Compiler - Transforming JavaScript for All Browsers.pptx
Babel Compiler - Transforming JavaScript for All Browsers.pptxBabel Compiler - Transforming JavaScript for All Browsers.pptx
Babel Compiler - Transforming JavaScript for All Browsers.pptx
 
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
UWB Technology for Enhanced Indoor and Outdoor Positioning in Physiological M...
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
 
Do we need a new standard for visualizing the invisible?
Do we need a new standard for visualizing the invisible?Do we need a new standard for visualizing the invisible?
Do we need a new standard for visualizing the invisible?
 
Cloud Revolution: Exploring the New Wave of Serverless Spatial Data
Cloud Revolution: Exploring the New Wave of Serverless Spatial DataCloud Revolution: Exploring the New Wave of Serverless Spatial Data
Cloud Revolution: Exploring the New Wave of Serverless Spatial Data
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8
 

Practices and tools for building better API (JFall 2013)

  • 1. Practices  and  Tools  for  Building  Better  APIs                                @PeterHendriks80,  +PeterHendriks
  • 2. Objectives  of  this  talk • API  from  a  Java  app  developer  perspective   ! • • • • Why  API  is  important   What  makes  a  better  API   Practical  tips  and  tools   Measuring  your  existing  codebase
  • 3. Some  API  terminology • API  Consumer:  code  that  uses  API   • API:  the  interface   • API  Implementer:  code  that  implements  API API   Consumer API API   Implementer Data  Access  Object JDBC Database  Driver
  • 4. We  are  using  a  lot  of  API Bazillion  Open   Source  Web   Framework  API’s   Spring:  27  API’s Java  EE:  37  API’s Java  SE:  45  API’s Enterprise  Service   API’s Public  Service  API’s Cloud  API’s Middleware  API’s
  • 5. We  are  building  more  of  them,  too • API  is  key  to  a  succesful  module  design   – Essential  for  agile  teams  at  scale Customer   Front-­‐End Warehouse   Front-­‐End Order   Management Shared  code
  • 6. Distance  to  API  implementation  is  increasing • API  quality  increasing  important  when   implementation  becomes  a  black  box Same   team Different   team Open   source Binary   only Other   datacenter
  • 7. The  API  we  use  shapes  our  code • Most  code  we  write  calls  an  API   • Code  that  calls  an  API  is  shaped  to  fit  the  API   • Therefore,  APIs  determine  the  shape  of   application  code   – In  some  ways,  even  more  impactful  than  high  level   design,  test  driven  development  or  code   craftsmanship
  • 8. ! http://docs.oracle.com/javaee/1.4/tutorial/examples/jaxp/xslt/samples/ TransformationApp04.java   ! public  class  TransformationApp04  {          public  static  void  main(String[]  argv)  {                  if  (argv.length  !=  1)  {                          System.err.println("Usage:  java  TransformationApp  filename");                          System.exit(1);                  }   !                //  Create  the  sax  "parser".                  AddressBookReader02  saxReader  =  new  AddressBookReader02();   var  json_data  =  JSON.stringify(obj);                try  {                          File  f  =  new  File(argv[0]);   ! !                        //  Use  a  Transformer  for  output                          TransformerFactory  tFactory  =  TransformerFactory.newInstance();                          Transformer  transformer  =  tFactory.newTransformer();   !                        //  Use  the  parser  as  a  SAX  source  for  input                          FileReader  fr  =  new  FileReader(f);                          BufferedReader  br  =  new  BufferedReader(fr);                          InputSource  inputSource  =  new  InputSource(fr);                          SAXSource  source  =  new  SAXSource(saxReader,  inputSource);                          StreamResult  result  =  new  StreamResult(System.out);                          transformer.transform(source,  result);                  }  catch  (TransformerConfigurationException  tce)  {                          //  Error  generated  by  the  parser                          System.out.println("n**  Transformer  Factory  error");                          System.out.println("      "  +  tce.getMessage());   !
  • 9. What  makes  a  better  API
  • 10. API  Quality:  Value • Value  =  benefits  -­‐  costs   • Benefits   – Features   – Data   – ...   • Costs   – – – – License/pay  per  use   Performance/footprint   Security   …
  • 11. API  Quality:  Usability • API  Design  ==  Human  Interface  design   – Although  API  is  for  machine/machine  interaction,   APIs  need  to  be  understood  by  programmers  to   write  the  code   – Programmers  are  humans API  is  not  just  about  capability  and  structural   design,  but  also  about  human  understanding
  • 12. A  simple  model  for  API  Usability Generic  usability  model  by  Ben  Shneiderman: Learnability:  How  easy  is  it  to  accomplish  basic   tasks  the  first  time?   Efficiency:  Once  users  learned  the  design,  how   quickly  can  they  perform  tasks?   Memorability:  When  users  return  after  a  while,   how  easily  can  they  re-­‐establish  proficiency?   Errors:  How  many  errors  do  users  make,  how   severe  are  these  errors,  and  how  easily  can  they   recover  from  the  errors?   Satisfaction:  How  pleasant  is  it  to  use  the  design?
  • 13. API  Quality:  stability Able  to  enhance/grow  implementation  without   breaking  existing  consumer  code Google  AppEngine  release  notes:   Version  1.7.5  -­‐  February  13,  2013   The  Conversion  API,  which  was  decommissioned  last  release,  has  been   removed  from  the  SDK.  In  a  future  release,  the  API  will  be  removed  from  the   runtime  and  applications  that  attempt  to  use  it  may  stop  working.  Applications   in  production  that  import  the  library  should  be  fixed  as  soon  as  possible.   Version  1.8.4  -­‐  September  9,  2013   The  Conversion  API,  a  decommissioned  feature,  has  been  removed  from  the   SDK.  In  the  next  release,  the  API  will  be  removed  from  the  runtime  and  any   attempt  to  import  the  API  will  raise  an  exception.   Version  1.8.5  -­‐  September  25,  2013   The  Conversion  API,  a  decommissioned  feature,  has  been  removed  from  the   runtime.  Applications  in  production  that  import  the  API  should  be  fixed  as   soon  as  possible.
  • 14. API  Quality:  A  hierarchy  of  needs Stability  only  matters  when   API  is  valuable  and  usable   Stable Usable Valuable
  • 16. API  Design:  start  with  examples • Examples  most  important  in  API   documentation   – Concrete  use  case,  usability  check   • Make  examples  exemplary   – Example  code  will  be  copy-­‐pasted   • Create  a  cheat  sheet   – Improves  learnability   – Shows  design  issues
  • 17. API  Design:  multiple  perspectives Names,  Completeness,   Grouping UML: public  class  Document  {   ! !    private  List<Page>  pages  =  new  ArrayList<>();   Impl: Consumer:    public  Page  addPage()  {          Page  page  =  new  Page();          pages.add(page);          page.setPageNumber(pages.size());          return  page;      }            public  void  report()  {...}   } Page  page  =  document.addPage();   page.setContents("Once  upon  a  time..."); Can  it  be  built? Is  it  usable?
  • 18. API  practice:  Keep  it  simple • Try  to  stick  to  just  methods  and  constructors   – Factories,  Delegates,  etc.  not  always  necessary   ! • “When  in  doubt  leave  it  out”   – Less  classes,  methods   – Less  parameters,  return  values Josh  Bloch,  Java  API  guru
  • 19. API  practice:  avoid  verbose  constructs • Constructs  that  create  verbose  consumer  code   – Extending  class/implementing  interface   – Checked  exception   – Required  casting   – Required  generic  type   – Required  if,  for,  while,  try/finally   – Required  synchronization/locking   – Hard  coded  parameter  value
  • 20. Example:  doing  some  loggin’ • Demo:  different  styles  of  logging  API
  • 21. Why  Lambdas  are  so  much  better  than  inner   classes • Inner  classes,  or  extending  existing  classes   often  needed   – Resource  handling   – Looping/visiting  collections   – Event  handling   • Lambdas  provide  a  much  more  usable   construct   – Shorter,  safer,  better  footprint/performance
  • 22. Example:  Lambda  benefits • Demo:  Netbeans  example
  • 23. API  practice:  fail  fast,  fail  hard • Fail  immediately  on  wrong  input   • Limit  the  use  of  null  as  valid  input/output public  void  save(String  filename)  {      if  (filename  ==  null)  {          return;  //  bad  api:  error  is  ignored!      }      ...  //  save  happens  here   } Better public  void  save(String  filename)  {      Objects.requireNonNull(filename);      //  Throws  NPE  immediately      ...  //  save  happens  here   }
  • 24. API  Tool:  checking  for  null • Tool:  FindBugs,  a  static  code  analyzer   – Reports  errors  at  compile-­‐time   • Annotations  for  Software  Defect  Detection
 (JSR  305:  Dormant)   – @Nonnull:  may  never  be  null   – @CheckForNull:  should  always  be  checked  before   dereferenced   – @Nullable:  caller  decides  if  null  check  is  needed   • Java  8  will  add  more  annotation  options  for  tools
  • 25. FindBugs  demo  in  Eclipse
  • 26. Finding  API  problems  in  your  code • People   – Team  knowledge   – Policy,  “best  practices”,  conventions   – Elaborate  explanation,  “hard  to  do”   – Defect  lists/exceptions/stack  traces   • Tools   – Finding  most  used  API:  Dependency  Structure   Matrix  (DSM)
  • 27. How  a  Dependency  Structure  Matrix  works Classes/Packages Document Document 2 TextBlock -­‐ Page Page TextBlock -­‐ 10 #  of  direct  dependencies  from   Document  to  Page -­‐
  • 29. API  design  cheat  sheet API  matters:   Reuse  3rd  party   Modular  design   Distance  to  impl. A  Better  API  is:   1. Valuable     2. Usable     3. Stable API  usability:   • Learnability   • Efficiency   • Memorability   • Error  rate   • Satisfaction API  Design  Perspectives:   UML:  names,  completeness,  grouping   Implementation:  can  it  be  built   API  usage:  how  usable  is  it   Examples  First JSR  305/FindBugs:   @Nonnull:  may  never  be  null   @CheckForNull:  always  check   @Nullable:  caller  decides  null  check DSM:  finding  most  used  API Document Document 2 TextBlock -­‐ Page Page TextBlock -­‐ 10                                @PeterHendriks80,  +PeterHendriks -­‐ API  Design  practices:   When  in  doubt  leave  it  out   Limit  API  consumer  code  to  a  minimum   • Extending  class/interface   • Checked  Exception   • Required  casting   • Required  Generic  Type   • Hard  coded  parameter  value   • Required  if,  for,  while,  try   • Required  synchronization/locking   ! Be  predictable  and  obvious   • Methods  calleable  in  any  order   • Constructor  should  only  construct   • Don’t  have  surprising  side  effects   • Limit  null  as  input/output   • Fail  fast,  fail  hard Eval!