I will need to build an API for a big project. Need advice.

Hi @t3rm1n4l I have done that and I have some tips that would have been good for myself

Use TDD for the endpoints always and since the beginning of the project, start with a test that checks the success API response, and that param/values are right.

Use all the opinionated classes that laravel has, for a simple crud it could be a little bit overwhelming but with time its a lot easier to maintain. Model, Controller, FormRequest, ApiResource, Middlewares. And use migrations properly always.

Keep your api restful with no more than 2 levels deep in routes. For example if you have a project where Hotels, have rooms, that have guests. Avoid using a route like /hotels/1/rooms/31/guest/1 for retrieving the data of a guest. If you could, just keep one level.

Use OpenAPI for documentation, there are other ways of documenting that are more automated, but OpenApi has several tools that will help the other developers see the details more easily.

In the response of the endpoints just add the attributes they need, dont give more data "just in case", when more data is needed if you follow the separation of concerns advice, it will really easy to add it later.

Don't worry a lot in the beginning with the performance of a response, just check that no response takes more than 2 seconds, later you could optimize by checking the queries.

Any specific doubt feel free to ask, happy to help. Regards

Hi, I've been working in a company for about 6 years and when I first started, I was in the same position as you've now. I've built a large application with an API integrated into it. And this API provides data access to various mediums.

So, my first advice is to spend more time in planning rather how you'll develop and what technology you'll use. Once, you start to create a plan for your project, you'll have some kind of direction on what technology you'll need to solve the problem.

However, developing API using Laravel is one of the best choice as long as you know exactly what you are going to do.

Here's some article you might read on how you can use to auto-generate documentation for your Laravel project.

Auto generate documentation

Here some more:

https://auth0.com/blog/developing-restful-apis-with-lumen/

https://www.slant.co/topics/6956/~php-frameworks-for-building-a-restful-api

https://www.bradcypert.com/building-a-restful-api-in-php-using-slim-eloquent/

https://www.codechief.org/article/laravel-passport-scope-tutorial-api-permissions-using-passport-scope

Those are some useful links to start off.

I will provide more and my personal experience if you wish.

Best of luck!

@t3rm1n4l Hey! I specialise in API development for a large e-commerce vendor, so would be happy to share some tips I’ve picked up along the way!

Laravel is great for building if you stick to its conventions. So resource controllers, form request validation, and resource classes for your responses.

In terms of responses, I’m a fan of the JSON:API spec. It defines a common format for representing resources (single records), relationships, errors, etc.

For documentation, OpenAPI is pretty much becoming the de facto standard for describing APIs. It’s basically YAML files describing the “shape” of your API’s requests and responses, so people know what data to give it, and what responses will look like. You can then build documentation from these descriptions.

A company called Stoplight have a product called Stoplight Studio which is a GUI editor for writing OpenAPI specs. It can then generate your documentation too if you need to publish it online or share it with third parties.

If you have any questions, let me know and I’ll be happy to answer them!

@punksolid Thanks a lot! What would you recommend for OpenAPI? @martinbean recommended a very nice tool (stoplight). I am wondering if I should use that or learn Swagger annotations and use it in the comments (although it looks really cumbersome...).

@t3rm1n4l Your OpenAPI specs would be YAML files in your repository.

Don’t add annotations to code. Like you say, it looks really cumbersome. It is ;)

@t3rm1n4l Well I have used this https://github.com/DarkaOnLine/L5-Swagger but its true that it looks bloated, the cool part its that the annotation its where your code is so its easier to update both and not forget.

Its up to you if you use annotations or https://stoplight.io/.

I would recommend Swagger. There is a bit of a learning curve to it and there are a few weird gotchas but I have not found anything better.