api design - developing for developers

Download API Design - developing for developers

Post on 16-Jul-2015




3 download

Embed Size (px)


Slide 1

API Developing for developersJoy George KArchitectwww.joymononline.inhttp://joymonscode.blogspot.com

API - D4D ImportantWhen in doubt leave it outAPI - D4D - Agenda Developing for developers v/s developing for users What is API Characteristics of best API Naming philosophy Usability Consistency Versioning Error handling Documentation, quick start examples Limitations / Compromises Performance Evangelism ConclusionAPI - D4D v/s D4U

Backward compatibleAPI - D4D v/s D4U

API - D4D v/s D4U

API - D4D v/s D4U SimilaritiesCant predict behaviorDifferencesDevelopers are same / more skilled than you.Chances of misuseDevelopers can think internals more than a user think.Applications can be patched easily but patch to developers require more effort @ their sideDX - Developer experience

API - D4D What is an APIDefinitionBoundaryInterfaceTypes Class / methodsSOAWho writes APIEvery developer

API - D4D What is an APISystem

Component BComponent AAPIAPI - D4D What is an APIPrimarySystemThird partySystemAPIAPI - D4D Naming PhilosophyUse same naming patterns /philosophyQueueMsg(),RequeueMessage() & Message_Dequeue() GetCustomerById(int id) & GetEmployee(int id) Use similar methods to do logically similar operationsButton.ChangeSize(size) & TextBox.Size = sizeSame meaning throughout the platformGetCustomerById(int id) & FetchEmployeeById(int id) Button.Draw & GridPainter.Paint(grid) Honor logical parameter order.FileCopy(source,dest) & StringCopy(dest,source)

API - D4D - UsabilitySelf learning / discoverableAvoid short namesIndicate units in parameter names timeoutInSeconds parameter instead of just timeoutAvoid overloads Eg:Prefer GetById(int id) & GetByName over Get(int id) and Get(string name)Limit method parameters to 3.Try to avoid same type parameters repeating more than twiceGetEmployee(joy,true,false,true,false)API - D4D - UsabilityStatelessUse state only for entity classes .Operation classes should never have state.Class Employee{int empId,string name}Class SalaryCalculator{ decimal Calculate(employee);}Avoid public fieldsOne method call should be independent of previous callAPI - D4D - UsabilityAbstract as much as possibleDo not expose internal detailsUse interface if there is a reason (Remember there is no IString)Loose couplingDependency injectionAPI - D4D - UsabilityWalk in the shoe of other developerStart by creating the contract and use it before coding the implementation.Do not give surprise to usersGetDocument() This method should not get the document by checking it outGetDocumentAfterCheckingout()Do not expose implementation details to usersSaveEmployeeIntoSQLServer(employee);SaveEmployee(employee);Separate application APIs from support APIsIQueueServiceQueue();IQueueAdminServiceRequeueAllFailedRequests();BackupQueueDataStore();API - D4D - UsabilityNo Boilerplate. This will help users to avoid copy paste


API - D4D - UsabilityAPI should not be a reason for writing bad app codeAPI - D4D - UsabilityOpen for extension Closed for misuse Have only required protected methodsMake use of the OOP conceptsMake classes as sealed Use factory patternAPI - D4D - UsabilityDo not have extreme generic method eg:DoTask( TaskType, object[]params)API - D4D - UsabilityLess but powerful methods if possible. Eg: GetSubListByFirstAndLastIndexes(first,last) instead of 2 GetFirsItemsTill() & GetLastItemsFrom()API - D4D - UsabilityDo not deviate much from the platform and language conventions.Take advantage of platform & language (eg: Generics, Extension methods, async etc)Do not reinvent the wheelClass Stack is already part of .Net frameworkDevelopers hate adding more and more references. Try to package more namespaces in same assemblies.Package base classes and default implementations in one dllUsers should be able to use your API by referring one dllExtensions to core classes should be packaged in different dll

API - D4D ImportantWhen in doubt leave it outAPI - D4D - ConsistencyDo what is intended and do it wellLog what & how it happened.Try creating multiple sample appsImplementation can change but without affecting the API.Return zero length array or empty collection when returning arrays. Never return null

API - D4D Versioning API are evolving. Not like constructing bridge You can add but cannot remove. Cannot write perfect API in first attempt. Gradual changes Think about developers and their apps in production before introducing change.API - D4D Error handlingTry to fail during compilationBad APIPublic void Queue(object queueType) {int typeId=int.Parse(,queueType)}User codeQueue(email); //Compiles but fail at runtime.GoodPublic void Queue(int queueType) {int typeId= queueType;//No need to parse}Queue(10); // It wont compile if we pass string.API - D4D Error handlingNever fail silentlyMake clear distinction between exception caused by user code and platform API codeLog error - what & how it happened.API - D4D - Documentation External Document public & Protected methods for sure A sample application is the best documentation Create quick start tutorials Videos which helps developers to productive in an hour. Document limitations. Internal Keep track of each and every decision. (Why its so?)API - D4D - Limitations Aware of limitations. One API cant satisfy everyone. So disappoint everyone equally.API - D4D - Performance Set your own bench mark Think twice how your code is going to be executed in the binary world, before writing every line of code. Should support scale up and down. Support horizontal scaling as well Support pagination via API GetEmployeesByName(string name, int from,int to); API should tell that it needs better hardware Via logsAPI - D4D - Evangelism Test, Test and Test. Self use. Proud of your API. Socialize the existence. Take sessions. Listen to developers and open to change Support developer. Reply to mails. Create evangelists.API - D4D ImportantWhen in doubt leave it outAPI - D4D Conclusion API Design is art than engineering No silver bullets Compromises are required Reward Quality improvement of the code you produceAPI D4D References http://lcsd05.cs.tamu.edu/slides/keynote.pdf https://www.youtube.com/watch?v=aAb7hSCtvGw http://www.apiacademy.co/ http://wiki.netbeans.org/API_Design http://wiki.apidesign.org/wiki/Main_Page http://www.ibm.com/developerworks/library/ar-servdsgn1/ http://media.wiley.com/assets/7255/37/9781118937228_custom.pdf https://docs.djangoproject.com/en/dev/misc/design-philosophies/ Books Practical API Design A Practical approach to API design The design of everyday thingsAre you ready to develop for developers ?Q & A Thank You