Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Practices	
  and	
  Tools	
  for	
  Building	
  Better	
  APIs

	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
  	
...
Objectives	
  of	
  this	
  talk
• API	
  from	
  a	
  Java	
  app	
  developer	
  perspective	
  
!

•
•
•
•

Why	
  API	...
Some	
  API	
  terminology
• API	
  Consumer:	
  code	
  that	
  uses	
  API	
  
• API:	
  the	
  interface	
  
• API	
  I...
We	
  are	
  using	
  a	
  lot	
  of	
  API
Bazillion	
  Open	
  
Source	
  Web	
  
Framework	
  API’s	
  
Spring:	
  27	
...
We	
  are	
  building	
  more	
  of	
  them,	
  too
• API	
  is	
  key	
  to	
  a	
  succesful	
  module	
  design	
  
– E...
Distance	
  to	
  API	
  implementation	
  is	
  increasing
• API	
  quality	
  increasing	
  important	
  when	
  
implem...
The	
  API	
  we	
  use	
  shapes	
  our	
  code
• Most	
  code	
  we	
  write	
  calls	
  an	
  API	
  
• Code	
  that	
 ...
!

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

!

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

...
API	
  Quality:	
  Usability
• API	
  Design	
  ==	
  Human	
  Interface	
  design	
  
– Although	
  API	
  is	
  for	
  m...
A	
  simple	
  model	
  for	
  API	
  Usability
Generic	
  usability	
  model	
  by	
  Ben	
  Shneiderman:
Learnability:	
...
API	
  Quality:	
  stability
Able	
  to	
  enhance/grow	
  implementation	
  without	
  
breaking	
  existing	
  consumer	...
API	
  Quality:	
  A	
  hierarchy	
  of	
  needs
Stability	
  only	
  matters	
  when	
  
API	
  is	
  valuable	
  and	
  ...
Building	
  Better	
  APIs
API	
  Design:	
  start	
  with	
  examples
• Examples	
  most	
  important	
  in	
  API	
  
documentation	
  
– Concrete	...
API	
  Design:	
  multiple	
  perspectives
Names,	
  Completeness,	
  
Grouping

UML:

public	
  class	
  Document	
  {	
 ...
API	
  practice:	
  Keep	
  it	
  simple
• Try	
  to	
  stick	
  to	
  just	
  methods	
  and	
  constructors	
  
– Factor...
API	
  practice:	
  avoid	
  verbose	
  constructs
• Constructs	
  that	
  create	
  verbose	
  consumer	
  code	
  
– Ext...
Example:	
  doing	
  some	
  loggin’
• Demo:	
  different	
  styles	
  of	
  logging	
  API
Why	
  Lambdas	
  are	
  so	
  much	
  better	
  than	
  inner	
  
classes
• Inner	
  classes,	
  or	
  extending	
  exist...
Example:	
  Lambda	
  benefits
• Demo:	
  Netbeans	
  example
API	
  practice:	
  fail	
  fast,	
  fail	
  hard
• Fail	
  immediately	
  on	
  wrong	
  input	
  
• Limit	
  the	
  use	...
API	
  Tool:	
  checking	
  for	
  null
• Tool:	
  FindBugs,	
  a	
  static	
  code	
  analyzer	
  
– Reports	
  errors	
 ...
FindBugs	
  demo	
  in	
  Eclipse
Finding	
  API	
  problems	
  in	
  your	
  code
• People	
  
– Team	
  knowledge	
  
– Policy,	
  “best	
  practices”,	
 ...
How	
  a	
  Dependency	
  Structure	
  Matrix	
  works
Classes/Packages

Document
Document

2

TextBlock

-­‐

Page

Page
...
Demo:	
  SonarQube	
  DSM
API	
  design	
  cheat	
  sheet
API	
  matters:	
  
Reuse	
  3rd	
  party	
  
Modular	
  design	
  
Distance	
  to	
  impl...
Upcoming SlideShare
Loading in …5
×

Practices and tools for building better API (JFall 2013)

3,727 views

Published on

Een belangrijke voorwaarde om goede en leesbare Java code te schrijven is om gebruik te maken van een goede API. Een goede API helpt ontwikkelaars om sneller hoogwaardige code te schrijven. Het ontwerp van een API is daarom belangrijk, zeker als er grotere systemen worden gerealiseerd in teamverband. Moderne ontwikkeltools als Eclipse, IntelliJ IDEA en FindBugs helpen met het schrijven van goede API, en het detecteren van slecht gebruik. Deze sessie gaat in op de laatste ontwikkelingen en mogelijkheden, inclusief nieuwe taalmogelijkheden in Java 8. Er wordt hierbij gebruik gemaakt van praktische situaties en concrete codevoorbeelden, gebaseerd op echte ervaringen in grote codebases. Met praktische tips en toegankelijke tools kan al een grote stap gemaakt worden om in de praktijk beter met API ontwerp om te gaan!

Published in: Technology, Education
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL eBOOK INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. PDF eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... 1.DOWNLOAD FULL. doc eBook here { https://tinyurl.com/y3nhqquc } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, CookeBOOK Crime, eeBOOK Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

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
  15. Building  Better  APIs
  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 -­‐
  28. Demo:  SonarQube  DSM
  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!

×