The Next Step to Build Better APIs — Consistent Data Structure
1 like•1,625 views
The document discusses the importance of consistent data structures in API development as part of an overall strategy for building effective APIs. It highlights various data formatting conventions and emphasizes the need for understanding the specific use case of an API to choose the appropriate structure. Additionally, it touches on the significance of meaningful HTTP status codes to enhance API reliability and predictability.
The Next Step to Build Better APIs — Consistent Data Structure
- 1. The Next Step to Build Better APIs — Consistent Data Structure by Andrew Turner https://by.dialexa.com/consistent-data-structures-the-next-step-to-building-an-api
- 2. Dialexa We are on a mission to make every company a great technology company. We work with organizations to define and execute digital transformation strategies to improve business operations and customer experiences. Our services include: • Multi-Year Technology Roadmap • Platform Engineering • User Experience Design • Custom Software Development • Hardware Prototyping /IoT
- 3. You don’t build good APIs through coding alone. Like any other part of your business, APIs are best when they are developed as part of a detailed, end-to-end strategy. Get the full write up of this slideshare HERE
- 4. However, there are multiple parts of a comprehensive strategy and understanding each piece is essential to building better APIs. Get the full write up of this slideshare HERE
- 5. In our first post about APIs, we talked about the need for a documentation- first strategy and how 3 main tools can help you build more effectively. Get the full write up of this slideshare HERE
- 6. The next natural step in the process is to choose an appropriate data structure formatting convention for API endpoint responses and ensure it is applied consistently—here’s how. Get the full write up of this slideshare HERE
- 7. Understand Your API Use Case Get the full write up of this slideshare HERE
- 8. We talk a lot about “starting with the why” for product development— starting small discovery projects and using design thinking to get to the heart of the problem your product will solve. Get the full write up of this slideshare HERE
- 9. Understanding the “why” is also an important concept when building APIs. Get the full write up of this slideshare HERE
- 10. The key is to determine your API use case. Is the API for a mobile app? Is it for front end use? Will it be public for third party developers? Get the full write up of this slideshare HERE
- 11. The “why” of your API will help you choose the right data structure convention for development. However, there are many different options to choose from. Get the full write up of this slideshare HERE
- 12. Common API Response Formatting Conventions Get the full write up of this slideshare HERE
- 13. To read more you can find the full article at https://by.dialexa.com/consistent-data-structures-the- next-step-to-building-an-api
- 14. JSON API JSON API is a community-driven specification for building APIs and formatting API responses. Get the full write up of this slideshare HERE
- 15. EmberData Ember is a framework for creating ambitious web applications. If you're building an API for an Ember application, you may want to consider using the EmberData convention for your API responses. Get the full write up of this slideshare HERE
- 16. Core API Another community-driven convention is Core API. Get the full write up of this slideshare HERE
- 17. Flat Response This is a simple and straightforward way to format your data structure that simply returns the data requested without a namespace object. Twitter and GitHub are popular APIs that follow this data structure formatting convention. Get the full write up of this slideshare HERE
- 18. Seeking the pros and cons of each data structure convention seems like a logical next step once you’ve listed your options. Get the full write up of this slideshare HERE
- 19. However, there is no single correct data structure convention. You should choose a convention based on what is pragmatic and intended for your API use case. Get the full write up of this slideshare HERE
- 20. It’s possible that a specific data structure convention would work best for your API's use case—for example, Vinli’s need to return telemetry data could command a different convention than a project management API that returns tasks and project updates. Get the full write up of this slideshare HERE
- 21. Generally, though, keeping your data structures consistently formatted will result in a better API. Get the full write up of this slideshare HERE Get the full write up of this slideshare HERE
- 22. When you establish your data structure convention from the outset of your project, you can better coordinate the “why” of your API and the way you’re building it. Get the full write up of this slideshare HERE
- 23. Then, you can include the data structure convention in your documentation and use Dredd to validate its use throughout the project. Get the full write up of this slideshare HERE
- 24. After you establish a formatting convention for your API's data structures, you should implement meaningful HTTP status codes to ensure your API responses are accurate. Get the full write up of this slideshare HERE
- 25. Find out where great products come from! Download or free eBook: https://by.dialexa.com/dialexa-end-to-end- development-guide-0
- 26. Status Codes Should Accurately Reflect Your API Response Get the full write up of this slideshare HERE
- 27. As you use Dredd to validate your data structure formatting, make sure you use the appropriate HTTP status code for each type of response. Get the full write up of this slideshare HERE
- 28. However, because there are so many HTTP status codes, it is important to pay attention to the right ones throughout your development process. Get the full write up of this slideshare HERE
- 29. At a higher level, there are 4 main HTTP status code categories: • 200 Level: The HTTP 2xx codes convey successful responses. • 300 Level: HTTP 3xx codes are reserved for redirects. • 400 Level: This Block of codes conveys errors that originate on the client side. • 500 Level: Similar to the 400 level codes, HTTP 5xx codes translate errors, but on the server side instead. Get the full write up of this slideshare HERE
- 30. To give you a better idea of the specific codes any engineer should know, we’ve compiled a list of the most important ones: Get the full write up of this slideshare HERE
- 31. By using these meaningful status codes, you can avoid sending 200 level status codes when your API is returning an error! Get the full write up of this slideshare HERE
- 32. You want your API to be predictable and easy to work with— ensuring status codes match the true API response is essential to building a better API. Get the full write up of this slideshare HERE
- 33. There’s More to APIs and Product Development Than Consistent Data Structures Get the full write up of this slideshare HERE
- 34. You won’t be able to build an effective API without proper documentation and consistent data structures. Get the full write up of this slideshare HERE
- 35. And you won’t be able to succeed with digital transformation projects if you can’t build better APIs. However, there’s much more to digital transformation product development than just APIs. Get the full write up of this slideshare HERE
- 36. PROPERTY OF DIALEXA LLC ©2017 - CONFIDENTIAL & PROPRIETARY Thank You Doug Platts VP of Marketing [email protected] If you want to learn more about the product development process and how your better APIs fit into the bigger picture, download our free ebook and discover how we combine business and innovation consulting, user experience design, software engineering and hardware engineering to create products that users love. Get the full write up of this slideshare at https:// by.dialexa.com/consistent-data-structures-the-next-step-to- building-an-api