Download - API Design - developing for developers

API – Developing for developers

Joy George K

Architectwww.joymononline.in

http://joymonscode.blogspot.com

http://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

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

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/

Are you ready to develop for developers ?

Q & A

Thank You

Download - API Design - developing for developers

Top Related