BIG NOTE
This article is currently in progress, but I love sharing while I’m writing, so take what you see as my writing notes. Once this BIG NOTE is gone, then this article is done. At the moment I am only mapping out my idea’s.
Summary
Being someone who regularly interacts with the APIs created by other people inspired me to produce this blog. I have experienced both excellent and terrible APIs, and I can say with confidence that the differences between them are what separate them into such stark categories.
- Some may appear to have comprehensive documentation, yet their behavior may differ from what is described. The developers’ failure to update the documentation alongside the code is clearly causing this issue.
- Other APIs may rely on antiquated protocols and data formats, such as SOAP and XML, making it challenging for developers to implement these APIs in modern languages without resorting to dated packages that may not even be compatible with the language in question.
- Mismash of Protocols
- Versioning of API’s
- Improper use of the protocol
- No Standards
- Overage or Underage of data
- Handling Breaking Changes
- API Verbiage being incorrect.
Goal
This blog and this endeavor is dedicated to developing the best possible API. The ideal application programming interface (API) doesn’t necessarily rely on the latest and greatest technology; instead, it prioritizes those that are straightforward for the average developer to adopt. However, the modern developer has extensive experience with REST and JSON, thus those technologies should be prioritized. The ideal API, however, would enable both with minimal upkeep even if GraphQL is now dominating the scene.
On top of that, the underlying technology needs to be extremely reusable, so even before developing the perfect API, you need to design the perfect base code structure that supports universal queries, filters and paging. This in turn will create a unified experience for the end developer no matter what data they are trying to access.
Proposal / Challange
Given the above issues in the Summary and the above Goals, the following are the goals of this Blog and project:
- A simple and reusable data structure compatible with SQL and NoSQL databases.
- Supports reusable methods on all data objects.
- Supports both the real RESTful and GraphQL requirements
- Self-documents.
Past Standards
SOAP
Soap was actually pretty cool but may have been way over engineered.
XML
XML was an attempt to create a structure that was already familiar like HTML but adding the data element to the structure.
New Standards
RESTful
RESTful API’s were both a step forward and a step backwards, but the backward step was genius. The original HTTP 1.1 protocol already supported the standard CRUD methods (Create, Read, Update and Delete) formats through the HTTP Verbs GET (Read), POST (Create), PUT (Update) and DELETE (Delete).
On top of that, if implemented correctly, there was no need for the server to store the state of any information, it was supposed to be stateless, hence RESTful.
The big struggle with RESTful API’s was what data do we give back? Do we give back the parent and all the children of the parent or do we give back a link to the children and require anther query for that information (This is where GraphQL) comes in?
Although modern day RESTful API’s typically use JSON, a real RESTful API should return the data based on the request Content Type
We know the data structure coming back, out DTO Data Transformation Object.
GraphQL
We get back only the data needed, works like SQL but kind of lacks structure
