API DesignAPIWhy is API Design Important?Characteristics of Good APIsDesigning an APIBroad Issues to Consider in Design1. Interface PrinciplesSimpleGeneralRegularPredictableSlide 12RobustAdaptable2. Resource ManagementResource Management3. Error HandlingFail FastError ManagementExceptionsSlide 21API DesignCPSC 315 – Programming StudioSpring 2009Follows Kernighan and Pike, The Practice of Programming andJoshua Bloch’s Library-Centric Software Design ’05 Keynote Talk: ”How to Design a Good API and Why It Matters”APIApplication Programming InterfaceSource code interfaceFor library or OSProvides services to a programAt its base, like a header fileBut, more completeWhy is API Design Important?Company ViewCan be asset – big user investment in learning and usingBad design can be source of long-term support problemsOnce used, it’s tough to changeEspecially if there are several usersPublic APIs – One chance to get it rightCharacteristics of Good APIsEasy to learnEasy to use even without documentationHard to misuseEasy to read and maintain code that uses itSufficiently powerful to satisfy requirementsEasy to extendAppropriate to audienceDesigning an APIGather requirementsDon’t gather solutionsExtract true requirementsCollect specific scenarios where it will be usedCreate short specificationConsult with users to see whether it worksFlesh it out over timeHints:Write plugins/use examples before fully designed and implementedExpect it to evolveBroad Issues to Consider in Design1. InterfaceThe classes, methods, parameters, names2. Resource ManagementHow is memory, other resources dealt with3. Error HandlingWhat errors are caught and what is doneInformation HidingHow much detail is exposedImpacts all three of the above1. Interface PrinciplesSimpleGeneralRegularPredictableRobustAdaptableSimpleUsers have to understand!Do one thing and do it wellFunctionality should be easy to explainAs small as possible, but never smallerConceptual weight more important than providing all functionalityAvoid long parameter listsChoose small set of orthogonal primitivesDon’t provide 3 ways to do the same thingGeneralImplementation can change, API can’tHide Information!Don’t let implementation detail leak into APIMinimize accessibility (e.g. private classes and members)Implementation details can confuse usersBe aware of what is implementationDon’t overspecify behavior of modulesTuning parameters are suspectRegularDo the same thing the same way everywhereRelated things should be achieved by related meansConsistent parameter ordering, required inputsFunctionality (return types, errors, resource management)Names matterSelf explanatoryConsistent across APISame word means same thing in APISame naming style usedConsistent with related interfaces outside the APIPredictableDon’t violate the principle of Least AstonishmentUser should not be surprised by behaviorEven if this costs performanceDon’t reach behind the user’s backAccessing and modifying global variablesSecret files or information writtenBe careful about static variablesPredictableTry to minimize use of other interfacesMake as self-contained as possibleBe explicit about external services requiredDocument!Every class, method, interface, constructor, parameter, exceptionWhen states are kept, this should be very clearly documentedRobustAble to deal with unexpected inputError Handling (see later)AdaptableAPI can be extended, but never shortenedHeavily used APIs likely will be extendedInformation HidingImplementation details should not affect API2. Resource ManagementDetermine which side is responsible forInitializationMaintaining stateSharing and copyingCleaning upVarious resourcesMemoryFilesGlobal variablesResource ManagementGenerally, free resources where they were allocatedReturn references or copies?Can have huge performance and ease of use impactMulti-threaded code makes this especially criticalReentrant: works regardless of number of simultaneous executionsAvoid using anything (globals, static locals, other modifications) that others could also useLocks can be important3. Error HandlingCatch errors, don’t ignore them“Print message and fail” is not always goodEspecially in APIsNeed to allow programs to recover or save dataDetect at low level, but handle at high levelGenerally, error should be handled by calling routineThe callee can leave things in a “nice” state for recovery, thoughKeep things usable in case the caller can recoverFail FastReport as soon as an error occursSometimes even at compile time!Use of static types, genericsError ManagementReturn valuesShould be in form the calling function can useReturn as much useful information as possibleSentinel values only work if function cannot return all possible values of that typeDefine pairs, or return another parameter to indicate errorsUse error “wrapper function” if neededConsistent way of marking, reporting error statusEncourages useBut, can add complexityExceptionsGenerally indicate a programming errorProgramming constructSet exception value (e.g. as return)Other program operation when exception thrownExceptions usually in global registryInclude information about failureFor repair and debuggingExceptions should generally be uncheckedAutomatically process globally, rather than require explicit checks over and overExceptionsOnly use in truly exceptional situationsNever use as a control structureThe modern GOTONever use exceptions for expected return valuese.g. Invalid file name passed to library is “common”, not an