The state of Laravel-based APIs - a personal research
Tags: api, rest, graphql, laravel
Published: 2018-06-12 08:02:33

---
title: The state of Laravel-based APIs - a personal research
published: true
description: A review of resources found around the web to help Laravel developers get an API up and running
tags: api, rest, graphql, laravel
---

> **Friendly disclaimer:** this is a quick and dirty post that I'm putting together as I research API resources to build an API for a project I'm working on, so I'm sorry for being so direct and to the point, and also for the number of levels and bullet points :)
> It was written in the order of "here only for the sake of completeness" down to "probably what we're going to use".

# TL;DR
- GraphQL should be the way to go only if your frontend sort of requires it. Needs a lot of boilerplate and manual sync between your Eloquent models and GraphQL-related code.
- JSON-API is the most respected standard that could face GraphQL, but on Laravel-land it renders you documentation-less. You'll probably have to write separate documentation on API Blueprint or something like that, and it might take you some time as well. You can also discover how to get Blueprint generated through a specific package (that bridges JSON-API with Dingo), but... good luck on that.
- Handwritten RESTful API... Do I need to comment on that? It's handwritten. Certainly not a good option for a medium or big API. `EOF`.


# Prologue: basic API requirements we had
- should have built-in documentation, that's not dependent on the developer to manually write it (think PHPDocs that magically autocomplete in your IDE)
- it needs to be blazing fast, as it will be used on a speed-sensitive user interface
    - here the features of field-selection from GraphQL or JSON-API come to my mind
    - obviously, a simple cache layer might also be helpful

-------------------------------

# Research and comparisons

## API type option 1: [GraphQL](https://graphql.org/learn/)
> **Short conclusion.** Doesn't seem trivial to be built, as there's a lot of boilerplate to be written that repeats information from Eloquent: GraphQL Types, Queries, and Mutations. That happens on both packages found, and neither of them helps by having a boilerplate-generator.

### Helpful Packages
- [By Folkore Atelier](https://github.com/Folkloreatelier/laravel-graphql)
- [By Rebing](https://github.com/rebing/graphql-laravel), based on Folklore's

-------------------------------

## API type option 2: RESTful
### Subtype 1: [JSON-API](http://jsonapi.org/)
> Conclusion: also not that trivial to work with, but seems simpler than GraphQL. However, documentation might be a weak point.

#### Helpful packages
##### [Nil's Laravel5-json-api](https://github.com/nilportugues/laravel5-jsonapi)
- Implements `include`, `fields`, `sort`, `page`
- Almost boilerplate-free with generic controllers
    - However, you still need to [configure Transformers](https://github.com/nilportugues/laravel5-jsonapi#step-3-definition), although they don't repeat much information from the Eloquent model
- No support for documentation generation. At all.

##### [Laravel5-json-api-dingo](https://github.com/nilportugues/laravel5-jsonapi-dingo)
###### Good points
Theoretically, brings together the best of both packages, including Dingo's features (Dingo is discussed later) such as Auth, Versioning, Rate limiting, Docs and Routes into laravel5-json-api (called L5JA from now on).

###### Bad points
- [it's not clear how documentation could be generated](https://github.com/nilportugues/laravel5-jsonapi-dingo/issues/8), as Dingo depends on annotations and L5JA is ideally based on a generic controller implementation. There might be other integration issues, as the examples do not clearly define how to bring both packages together, besides a basic routing sample.
- [support also seems to be lacking behind](https://github.com/nilportugues/laravel5-jsonapi-dingo/issues/7).

##### [cloudcreativity's Laravel-json-api](http://laravel-json-api.readthedocs.io/en/latest/)
This one has very long documentation; while seems complete, it might take a while to read everything and implement (took me a while reviewing the docs to see what features were available). And there are at least two empty pages, with a simple "todo" note.

###### Good points
- also sort of boilerplate-free with generic controllers, and basic code generation for the other things (Adapters, Schemas)
- Adapters and Schemas will still need some filling and manual sync with the Eloquent model, though
- Also sports first-class validation rules for the API (which might end up being duplicated on your code, just like Eloquent details....)
- seems to have a decent Auth infrastructure

###### Bad points
- no clear mention on the docs about the selection of fields, and missing docs for sorting and "sparse fieldsets" (if that what I called "selection of fields"?) ([issue on the topic](https://github.com/cloudcreativity/laravel-json-api/issues/193))
- [filtering must be hand-written](http://laravel-json-api.readthedocs.io/en/latest/fetching/filtering/#using-filter-parameter) as well, there's no automatic API to turn filter parameters into Eloquent queries (much like GraphQL queries are built... sad).
- also, no mention about documentation generation. There's an [old issue](https://github.com/cloudcreativity/laravel-json-api/issues/94) that states Swagger can't work together with JSON-API, and the main developer doesn't have time to dedicate to that (we all know how open-source is born and dies, right? Free developer time during the lifecycle of a related project...)


### Subtype 2: Plain "bring-your-own-standard" JSON API
> Conclusion: the easiest to be built in our case, as we might end up needing only a couple of read-only endpoints. Might need some boilerplate to allow for field selection or advanced querying capabilities, but generates Blueprint documentation files and might even generate HTML docs with other generators.

#### Helpful Packages

##### [Dingo](https://github.com/dingo/api/wiki)
###### Good points
- complete feature-set: auth, rate limiting helpers, errors, routing, doc generator (through Blueprint files)
- Blueprint files can be used with a number of parsers to, then, generate HTML documentation or similar. Options and related resources are listed at the bottom of this post.

###### Bad points
Well... you'll have to write all your controllers and actions by hand. And define all your filters, if any. And whatnot.

##### [Restler](https://github.com/Luracast/Restler)
> This is actually unrelated to Laravel, but Eloquent can be easily made to work with it, so it's worth mentioning as a companion project to your main Laravel application.

###### Good points
- complete feature-set, including Swagger documentation based on PHP Doc blocks and method parameters (that are also used for automatic request validation)

###### Bad points
Got abandoned:
- stopped on PHP 5.4 support, while could have a great usage of PHP 7 first-class types
- stopped on an old version of Swagger, missing some of its features - probably one of the reasons the package got abandoned, as Swagger is sometimes referred as a very complicated beast to deal with.

###### Sample implementation
Once upon a time, I started working on an [API Server](https://bitbucket.org/dal-glossary/server/src/master/) build with an Eloquent extension (also sort of abandoned) and Restler. It included some base controllers that made CRUD actions only a couple of lines away.

## Other useful resources
- [Apiary](https://apiary.io/) - complete toolset (needs clarification!) to define, document and work on APIs.
- [Apimatic's transformer](https://apimatic.io/transformer) - UI and API that can translate to/from almost any doc format. Could be integrated in the API generation pipeline.
- [Dredd](https://github.com/apiaryio/dredd) - parses Blueprint/Swagger docs and automatically runs tests to ensure the Backend complies with the defined documentation.
- [Blueman](https://github.com/pixelfusion/blueman) _[probably outdated]_ - Generates Postman collections based on Blueprint files
- [PHPDraft](https://github.com/SMillerDev/phpdraft/) - basic HTML generator from Blueprint files
- [Laravel Blueprint docs](https://github.com/M165437/laravel-blueprint-docs) - generates integrated documentation inside your Laravel project, using its routing, and Blade templates for further customization.