API Design - developing for developers

API – Developing for developers
Joy George K
Architect
www.joymononline.in
http://joymonscode.blogspot.com

API - D4D – Important
When in doubt leave it out

API - 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
• Conclusion

API - D4D v/s D4U
Backward
compatible

API - D4D v/s D4U
• Similarities
• Can’t predict behavior
• Differences
• Developers are same / more skilled than you.
• Chances of misuse
• Developers can think internals more than a user think.
• Applications can be patched easily but patch to developers require more effort @ their side
• DX - Developer experience

API - D4D – What is an API
• Definition
• Boundary
• Interface
• Types
• Class / methods
• SOA
• Who writes API
• Every developer

System
Component B
Component A
API

Primary
System
Third
party
System
API

API - D4D – Naming Philosophy
• Use same naming patterns /philosophy
• QueueMsg(),RequeueMessage() & Message_Dequeue()
• GetCustomerById(int id) & GetEmployee(int id) –
• Use similar methods to do logically similar operations
• Button.ChangeSize(size) & TextBox.Size = size
• Same meaning throughout the platform
• GetCustomerById(int id) & FetchEmployeeById(int id)
• Button.Draw & GridPainter.Paint(grid)
• Honor logical parameter order.
• FileCopy(source,dest) & StringCopy(dest,source)

API - D4D - Usability
• Self learning / discoverable
• Avoid short names
• Indicate units in parameter names – timeoutInSeconds parameter instead of just timeout
• Avoid 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 twice
• GetEmployee(“joy”,true,false,true,false)

• Stateless
• Use state only for entity classes .Operation classes should never have state.
• Class Employee{int empId,string name}
• Class SalaryCalculator{ decimal Calculate(employee);}
• Avoid public fields
• One method call should be independent of previous call

• Abstract as much as possible
• Do not expose internal details
• Use interface if there is a reason (Remember there is no IString)
• Loose coupling
• Dependency injection

• Walk in the shoe of other developer
• Start by creating the contract and use it before coding the implementation.
• Do not give surprise to users
• GetDocument() This method should not get the document by checking it out
• GetDocumentAfterCheckingout()
• Do not expose implementation details to users
• SaveEmployeeIntoSQLServer(employee);
• SaveEmployee(employee);
• Separate application APIs from support APIs
• IQueueService
• Queue();
• IQueueAdminService
• RequeueAllFailedRequests();
• BackupQueueDataStore();

No Boilerplate. This will help users to avoid copy paste
• Bad
• queue=QueueFactory.GetQueue()
• queue.Initialize()
• queue.SetName(“email”)
• queue.Insert()
• Good
• queue=QueueFactory.GetInitializedQueue(“email”)
• queue.Insert()

• API should not be a reason for writing bad app code

• Open for extension Closed for misuse
• Have only required protected methods
• Make use of the OOP concepts
• Make classes as sealed
• Use factory pattern

• Do not have extreme generic method eg:DoTask( TaskType, object[]params)

• Less but powerful methods if possible. Eg: GetSubListByFirstAndLastIndexes(first,last) instead of 2
GetFirsItemsTill() & GetLastItemsFrom()

• Do not deviate much from the platform and language conventions.
• Take advantage of platform & language (eg: Generics, Extension methods, async etc…)
• Do not reinvent the wheel
• Class Stack is already part of .Net framework
• Developers hate adding more and more references.
• Try to package more namespaces in same assemblies.
• Package base classes and default implementations in one dll
• Users should be able to use your API by referring one dll
• Extensions to core classes should be packaged in different dll

API - D4D - Consistency
• Do what is intended and do it well
• Log what & how it happened.
• Try creating multiple sample apps
• Implementation 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 handling
• Try to fail during compilation
• Bad API
Public void Queue(object queueType) {
int typeId=int.Parse(…,queueType)
}
User code
Queue(“email”); //Compiles but fail at runtime.
• Good
Public void Queue(int queueType) {
int typeId= queueType;//No need to parse
}
Queue(10); // It wont compile if we pass string.

API - D4D – Error handling
• Never fail silently
• Make clear distinction between exception caused by user code and platform API code
• Log 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 can’t 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 logs

API - 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 – Conclusion
• API Design is art than engineering
• No silver bullets
• Compromises are required
• Reward – “Quality improvement of the code you produce”

API – 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 things

Are you ready to develop for developers ?
Q & A

API Design - developing for developers

More Related Content

What's hot (20)

Viewers also liked (9)

Similar to API Design - developing for developers (20)

Recently uploaded (20)

API Design - developing for developers