Practices and tools for building better APIs
Upcoming SlideShare
Loading in...5
×
 

Practices and tools for building better APIs

on

  • 311 views

 

Statistics

Views

Total Views
311
Views on SlideShare
275
Embed Views
36

Actions

Likes
0
Downloads
2
Comments
0

1 Embed 36

http://www.nljug.org 36

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Practices and tools for building better APIs Practices and tools for building better APIs Presentation Transcript

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