CSCE 315 Lecture 8

« previous | Friday, February 6, 2012 | next »

API

Application Programming Interface

Source code interface for library or OS to provide services to a program. (Just the stuff that the user needs to see)

Similar to a header file, but more complete.

• well-documented

Importance

• Can be an asset to big user investment in learning and using.
• Once used, it's tough to change.
  • E.g. Public API - One chance to get it right.

Characteristics of Good APIs

1. Easy to learn
2. Easy to use even without documentation (good names and logical data types)
   • Regularity and consistency across functions
3. Hard to misuse
4. Easy to read and maintain code that uses it
5. Sufficicently powerful to satisfy requirements
6. Easy to extend
7. Appropriate to audience

Designing an API

1. Gather requirements (not "solutions")
   • Use specific scenarios where it will be used
2. Create a short specification (check with users to see if it works)
   • Smaller API is better (just enough to do one thing well)
3. Interface (classes, methods, parameters, names)
4. Resource management (memory and other resources)
5. Error handling (what errors are caught and what is done)
   • Handle errors at the callee level
   • Fail fast! Report errors as soon as they are detected
6. Information hiding (how much detail is exposed)