API Design 1 Application Programming Interface API An

API Design 1

Application Programming Interface (API) An API is a kind of interface as well – one designed for developers. You may be familiar with several: OS, language, graphics, GUIs, network protocols. Even if not writing a library, in a large code team, your code is an interface to other developers 2

Bezos Mandate 1. 2. 3. 4. 5. All teams will henceforth expose their data and functionality through service interfaces. Teams must communicate with each other through these interfaces. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network. It doesn’t matter what technology they use. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions. It ended with: Anyone who doesn’t do this will be fired. 3 https: //www. cio. com/article/3218667/have-you-had-your-bezosmoment-what-you-can-learn-from-amazon. html

Using what we know from this class, how might we design an API? 4

Methods for Improving Design principles 1. Follow iterative processes that lead to improved design 1. Reduce iterations by grounding What principles design in design principles and knowledge humanimportant capabilities are of most Design you think process do for APIs? 2. Conduct evaluations on our designs and principles 5 Evaluation

Shneiderman S 1. Strive for consistency S 2. Seek universal usability S 3. Offer informative feedback S 4. Design dialogs to yield closure S 5. Prevent errors S 6. Permit easy reversal of actions S 7. Keep users in control S 8. Reduce short-term memory load Nielsen 1. Visibility of system status 2. Match between system and the real world 3. User control and freedom 4. Consistency and standards 5. Error prevention 6. Recognition rather than recall 7. Flexibility and efficiency of use 8. Aesthetic and minimalist design 9. Help users recognize, diagnose, and recover from errors 10. Help and documentation 6 Norman N 1. Discoverability N 2. Feedback N 3. Conceptual Model N 5. Affordances N 4. Signifiers N 5. Mappings N 6. Constraints

Design Principles for APIs 1. Abstract/Model a Problem: API should solve a particular task in a general way 2. Minimal Completeness: API should be as small as possible, but no smaller (“when it doubt, leave it out”) 3. Discoverable: Model and naming intuitive and logical 4. Consistent: Names, objects, behavior, other APIs 5. Orthogonal: There should be no side effects, minimal overlap in exposed concepts 6. Loosely Coupled: Components should have few connections 7. Robust: Stable and tested 8. Documentation: API isn’t an API without documentation Martin Reddy, API design for C++

Iterative Design Process Preliminary Investigation Identify Need (Re-)Design System Create representation of System Identify changes to be made Evaluate Outcome 8

Preliminary Investigation & Identifying Needs Recall: Functional & Non-Functional Requirements Non-Functional: • Performance • Platforms supported • Security • Scalability • Concurrency • Cost Functional: • The intended functionality of the API • What does the system do? Martin Reddy, API design for C++ 9

Considerations In Determining Requirements When collecting data… • What are users trying to achieve? • What is their ideal workflow? • What kinds of inputs should the API expect (types, value ranges)? • What kinds of outputs should the API generate (types, formats, value ranges)? • What formats & protocols must it support? • What is their central mental model? • What terminology do they use? Martin Reddy, API design for C++ 10

Requirements, Users, and Use Who are the users? • Develop personas What are the uses? • Develop use cases. Use cases should NOT assume any design but focus on tasks. • Alternatively, “user stories, ” which are at a slightly more abstract level, popular in Agile. From requirements, personas, and scenarios, identify key nouns, behaviors, and properties to help develop model. Martin Reddy, API design for C++ 11

Iterative Design Process Preliminary Investigation Identify Need (Re-)Design System Create representation of System Identify changes to be made Evaluate Outcome 12

Applying the Design Principles: Naming • Name classes/objects after their piece of the model and purpose • Abstract/base classes and interfaces should be named with adjectives for purpose • Functions should be named for what they do • Use Get, Set, Is, Are, Has liberally • May be specific with Save, Print, etc. • Functions not already associated with an object (e. g. , non-member functions) should have their associated object in the name • e. g. , open. File() and format. String() Martin Reddy, API design for C++ 13

Applying the Design Principles: Naming Should convey relation to model and purpose. If this requires too many characters, you may be trying to do too much in one class or function. Example: Suppose you have a function that calculates the bill total and closes the order. • checkout() is not descriptive as the total calculation is unclear • calculate. Total. And. Checkout()is descriptive but too long, suggesting this function does too much. • Divide into two functions calculate. Total() and checkout() Martin Reddy, API design for C++ 14

Applying the Design Principles: Naming • Use terms consistently: • Should not have get. Previous. Vertex() and get. Next. Node() • Avoid abbreviations, especially unknown ones • Use abbreviations consistently: • Should not have both get. Prev. Vertex() and get. Previous. Edge() • Names should make clear what something does: • is. Empty() vs empty() • Use natural pairs, e. g. undo/redo, get/set Martin Reddy, API design for C++ 15

Applying the Design Principles: Parameters var get. Substring = function(s 1, s 2) Vs. var get. Substring = function(target. String, match. String) How many parameters? • Recall Miller’s law – keep number of parameters low, <5 • If you need more and they’re optional, bundle in an object Martin Reddy, API design for C++ 16

Applying the Design Principles: Documentation var my. Color. API = {}; my. Color. API. set. Red = function (red. Value) { // }; my. Color. API. set. Green = function(green. Value) { // }; my. Color. API. se. Blue = function (blue. Value) { // }; my. Color. API. get. Red = function () { // }; my. Color. API. get. Green = function() { // }; my. Color. API. get. Blue = function () { // }; What are the valid values? What happens if you input a value outside of them? Martin Reddy, API design for C++ 17

Design Rationale Along with your requirements and designs should be a written design rationale. Users of an API have difficulty learning and using APIs if they don’t understand the API’s high level architecture of the intent behind its design. (Robilliard 2009) Martin Reddy, API design for C++ 18