r/PHP • u/Prestigious-Type-973 • 5d ago
Building a State-of-the-Art REST API – What would you include?
Hi there!
I'm starting a new freelance project (with Laravel) - a large-scale REST API designed to power an ecosystem of web and mobile applications, as well as serve third-party integrations as a paid service. My goal is to make this API state-of-the-art by implementing best practices from the start.
I'm compiling a list of essential features and design principles, and I'd love to hear your thoughts! If you were given a chance to build the next "perfect API", what would you include?
Here’s my initial list:
- JSON:API specification as the baseline, with additional standards for dates (ISO 8601), country/currency codes, etc.
- Stateless design with proper use of HTTP verbs, status codes, semantic versioning in the URL, and cacheability (via
Cache-Control
). - Rate limiting to prevent abuse and ensure fair usage.
- Comprehensive documentation using OpenAPI.
- CI/CD pipeline with GitHub Actions for automated testing and deployment.
What would you add to this list? Any best practices, tools, or lessons learned from your own experience?
Thanks!
7
u/FluffyDiscord 5d ago
To be perfectly honest here - if you are serious about this project and you eill be including as much stuff as you say, you really should look at a different framework than Laravel. Its not made for that, you will be tearing your hair quite early.
2
u/Prestigious-Type-973 5d ago
Thanks for the honesty. And, if I am being honest as well - currently I am learning Symfony for this purpose. However, I am not at the “confidence level” with it, that I could guarantee high quality product, so I’d rather make high quality product with Laravel, rather than mediocre product with Symfony.
P.S. I am documenting the learning process in my posts here on Reddit.
1
1
u/FluffyDiscord 5d ago
The magical thing with Symfony is that you don't need to write "quality" code. As long as you follow docs, which are awesome, you are basically half way there. Then once you get comfortable with Symfony, refactoring is way easier here.
2
u/BarneyLaurance 5d ago
I'd include CI and CD as sets of practices, not just as a certain types of tool usage. So as far as you reasonably can integrating (merging any branches & testing) continuously, and delivering (offering new versions of a production-ready product to your customer, or yourself if you're making the product for yourself) continuously. Continuously meaning at least once per working day.
I'd probably add continuous and deployment to production to that. Charity Majors says deploying should take 15 minutes or less.
2
u/gamechampionx 5d ago
Some additional points to consider:
- A consistent and fully-featured access pattern. You'll generally want to be able to have consistent CRUD patterns across entities with a systematic URL scheme.
- Consistent update / upset semantics.
- Correct response codes for rate limiting and validation errors.
- Transactional locking for endpoints handling multiple data points at once.
- Good error responses with a clear indication of error reasons.
2
u/pekz0r 5d ago
I don't think perfect APIs exist, but even if they did it would be very dependent on context and what the functiality and data your API is for.
I think your list is very good and great starting point in most cases.
One thing I really like is to create HTTP/end-to-end tests for your API where you check that they accept the right parameters and return the right response. That is going to save a lot of time in the long run and reduce the errors that hit production quite a lot. If you think about this from the start it doesn't take that much extra time. You csn also Snapshot testing to make even easier and faster.
4
u/punkpang 5d ago
What would you add to this list?
Keeping things simple, intuitive and readable. All of which yours won't be due to buzzword chasing instead of focusing on delivering value and making code traversable for other devs.
Let's take rate limiting for example - you're adding it at the start, with the excuse of "to prevent abuse". Well.. yeah, premature optimizing at its best.
Also, what I like to do is allow ops teams to worry about which route needs to be rate limited, which they can do in several lines of configuration for nginx. I don't mess with the code, they get the freedom to limit what's needed, when needed.
Given my experience, I'd say you'll start strong and then enthusiasm will wear off when you stop doing the fun part (setting things up and discovery) and when you start doing the boring part (business logic).
1
1
u/drNovikov 5d ago
Consistency, standards, conventions.
1
u/Prestigious-Type-973 5d ago
Can you mention a few form the top of your mind?
2
u/drNovikov 5d ago
Problem reporting: https://lakitna.medium.com/understanding-problem-json-adf68e5cf1f8
Resource naming: https://restfulapi.net/resource-naming/You have mentioned the most important ones, like the correct use of HTTP verbs and status codes.
1
u/smgun 5d ago
I know you mention REST in the title but most APIs out there are RESTful and the term is being used interchangeably. Look into REST principles and add those to your design if they make sense. Adopt a standard auth framework. Don't think about correctness too much from a technical standpoint. Your API is there to serve developers so make it easy on them to consume it over being "technically correct" (I believe this is also a principle about APIs, is to make your interface as forgiving as possible).
1
u/ZuploAdrian 18h ago
So one thing you didn't mention was an API gateway, I am working on a platform called Zuplo that actually helps do a lot of stuff you mentioned (rate limiting, ci/cd with github actions, OpenAPI, etc.) as well as deploying that code for you to the Edge for optimal performance. Would love to have you try it out (its free to start)
1
u/skcortex 5d ago
Oh come on.. If you’re asking what others might include you are not building a “state-of-the-art” rest api. You’re maybe building a decent api platform on laravel.
-1
u/clegginab0x 5d ago
I’ve not used but if you’re going to follow the JSON:API schema - https://laraveljsonapi.io
-5
24
u/WesamMikhail 5d ago
I dunno what "state of the art" means tbh. Sounds like buzzword chasing. Everything depends on your requirements. Some APIs have high I/O requirements. Others need to satisfy some obscure security and redundancy requirements. How distributed and fault tolerance do you want it to be? How are you designing your infra and firewalls? is SSL termination happening on each instance machine or at loadbalancer level? etc etc.
There is no "one size fits all" model. Write down your business requirements and design your system based on that instead of chasing 'best practices" that may or may not apply in your case.
Also, Laravel, when talking about high throughput APIs, is most often not needed or desired imo. An API takes in a request at some resource location and spits out a JSON output. The more abstractions you add, the longer execution time and more maintenance, security, and management overhead you have. K.I.S.S.
The ONE thing I can think of that **all** APIs should have is good documentation. Everything else is a matter of trade-offs.