Build Better API

Tips for building better API

Transcript

1. Building Better APIs Remy Muhire - @kenessa_jr
2. Speaker ‣ Co-founder, CTO at Exuus ‣ Software Developer ‣ Open Sourcer at Pindo ‣ Community Builder at forLoopRwanda ‣ Kigali FIFA18 Championship Organiser ‣ Live in Kigali, Rwanda Twitter: @kenessa_jr Github: @kenessa Speaker Deck: @kenessa
3. What’s is an API? An API it’s an Application Programming Interface. API’s allows external system to interact with the given system. A real world example: Gearstick, Accelerator, Steering wheels all interact with your car.
4. You can drive your parents VOLKSWAGEN because the API is the same as your car
5. Flask-Python API example
6. Why Building Better APIs? ✤ To provide a seamless experience to developers when writing software (Developer Experience). ✤ To increase developers efficient and to make easier for developers and achieve goal on the behalf of the users.
7. Most Telecommunication company in Africa are still using SOAP service for Mobile Money API.
8. Tips for writing better APIs
9. URL When designing an API you need to understand REST (REpresentational State Transfer). REST is the standard architecture for building APIs REST allow separating your API into logical structure which are (GET, POST, PUT, DELETE, PATCH) Example of RESTful API Endpoints (URL HTTP Method Operation) You can choose https://api.example.com/* as url root
10. Naming ✤ use plural for all your endpoints (even when you want a single value) ✤ user nouns and not verbs in endpoints ✤ Make sure the name are largely self-explanatory ✤ avoid abbreviation ✤ make sure it’s readable and easy to use
11. Versioning ✤ Versioning is a must as it gives your API stability and consistency ✤ There are various strategy to version your API ✤ Versioning with the URL
 Example: api.example.com/v1/ ✤ Versioning trough the content negotiation
 Example: Accept: version=2

12. Response ✤ Two thing you need to consider when return API response ✤ Response Payload ✤ HTTP status code
13. Date & time ✤ Avoid returning unix_timestamps, they don’t have timezone support ✤ Always return date & time in UTC
14. Errors ✤ A good API must use https status code to describe return value ✤ HTTP standard provides 70 status codes to describe the return value
15. Pagination Pagination allows the Client to specify the number of “data per page” and the “page number” for each end point.
16. Token Web Authentication Token web authentication are nowadays the most used in api development
17. Documentation ✤ Developer Friendly ✤ Easy to learn ✤ Easy to use ✤ Showing example of complete response
18. Thank you ✤ Rwanda ✤ Slide available on https://speakerdeck.com/kenessa/ build-better-api