Symfony-docs: Add new articles about REST APIs

[wouterj]

We currently completely ignore this topic, while it is a quite populair topic these days. https://github.com/symfony/symfony-docs/pull/4022 started discussing this, but it didn't have a lot of progress.

[94noni]

+1 for this
and maybe a simple demonstration in the symfony-demo app could be useful (https://github.com/symfony/symfony-demo/issues/69#issuecomment-105039876)

[marioaojeda]

+1!

[bocharsky-bw]

It will be useful :+1:

[wouterj]

As I don't have a lot of REST experience, I would be happy if people could indicate what exactly will be usefull. What are the problems you're facing with REST in Symfony? Where did you find help? What would you like to see in the official docs?

[timglabisch]

i think we should split this to a bunch of different articles.
rest is quite complex and there are so much topics and so much different ways to implement them :)

[bocharsky-bw]

Yes, you're right, it's a quite complex.
I think @weaverryan could propose some REST problems and give advice about structure in generally, if he has a time.

[weaverryan]

Best advice: start small - the previous effort was huge. A short tutorial showing the following would go along way:

A) Controller route methods
B) Grabbing and decoding JSON from the request body
C) Returning JSON directly (no serializer)
D) Using the serializer to return JSON
E) Controlling status codes
F) Controlling the request format

It is indeed such a big complex thing, that I think it's paralyzing. Whenever we give an example anywhere, we should think about using a template sometimes, and making something an "API" endpoint in another.

[ghost]

+1

[dudemelo]

:+1:

[fdyckhoff]

+1

[weaverryan]

This is a huge, and not-well-defined task. In general, we need to be more API-centric in the docs, but I don't think anyone is going to take the time to create a huge new section (unless I or a few core contribs find time to do it).

For those that _are_ looking here, I worked/am working on http://knpuniversity.com/screencast/symfony-rest. The scripts are free and the code-blocks below are expandable so you can get a full context. If there are parts of this that people would specifically find useful in the core docs, I'd be happy to help bring those over. Start with small, executable goals :).

[javiereguiluz]

I'm copying below a comment from @michaelperrin about this in a duplicated issue that we closed.

---

With the rise of APIs and service-oriented architecture, it would be great to have a starting point on how to build REST APIs with Symfony and some third-party bundles making it easier.
The current documentation is still very MVC-centric, although consuming APIs with JavaScript frameworks(for instance) gets very common. There are many tutorials and many ways to build REST APIs, but I think that newcomers would be glad to find such a starting point.

A step-by-step example would be appropriate, with an API built upon a simple entity (with a least one relation), with the main operations (create, update, delete, show, search) being impletend. The following subjects could be mentioned:

• Quick reminder of HTTP verbs
• HATEOAS
• API documentation (NelmioApiBundle / Swagger)

Should the API be built with Dunglas Core Api Bundle or FOSRestBundle? I like the pragmatic approach of Dunglas Bundle and the strong focus on standards, but I have no experience with it yet, and it may be out of the scope of the main Symfony documentation.

We should either way choose one very pragmatic approach, so that users don't get confused and overwhelmed by the many possibilities. Other possibilities could however be mentioned.

---

I'm also asking for help in the Symfony Slack to see if some truly expert in Symfony + APIs can share with us the modern best practices about that so we can start writing some articles. Thanks!

[gnugat]

javiereguiluz:
Thank you all! So, those of you that spend most of your time writing APIs with Symfony, could you please add a comment in this issue https://github.com/symfony/symfony-docs/issues/5260 with a bullet list of your "best practices". There's no need to explain things in detail for now. Just a bullet list of things to do and not to do. And if you know excellent and modern references (code, doc, blog posts) about this, please share them too. Thanks! (edited)

Here's my humble contribution, a bullet list of the steps we follow to create a new endpoint:

1. create a Controller class
2. configure its routing
3. register the controller as a service

We might need to create some event listeners (to populate $request->request when receiving JSON content, or to convert exceptions to responses).

The endpoint's logic is then up to us, it doesn't have to be done in a "Symfony" way. For example we can:

• extract Request parameters and put them in a class that validates them
• pass the class to a handler that will call services to do the actual logic
• define our services as interfaces, and then create implementations to integrate them with third party libraries

Here's an example of such a controller:

<?php
// src/AppBundle/Controller/Api/FortuneController.php

namespace AppBundle\Controller\Api;

use AppBundle\Service\SubmitNewFortune;
use AppBundle\Service\SubmitNewFortuneHandler;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class FortuneController
{
    private $submitNewFortuneHandler;

    public function __construct(SubmitNewFortuneHandler $submitNewFortuneHandler)
    {
        $this->submitNewFortuneHandler = $submitNewFortuneHandler;
    }

    public function submit(Request $request): Response
    {
        $submitNewFortune = new SubmitNewFortune(
            $request->request->get('content')
        );
        $this->submitNewFortuneHandler->handle($submitNewFortune);

        return new Response('', 201);
    }
}

[adamquaile]

As Symfony generally does not enforce certain techniques or conventions, is it worth mentioning that REST is not the _only_ way to build APIs. Perhaps a note about how to choose whether REST is the right choice when starting a new build..?

[fbourigault]

Does it worth to write a large documentation for building an API with Symfony? Or does we just need a smaller one that just explain some basic things and redirect users to Api Platform/FOSRestBundle?

I would chose the 2nd option as Api Platform works out of the box and require less work than the simplest hand made REST API.

[linaori]

Personally I'm not a fan of FOSRestBundle _at all_. So I would love to see ways of doing so _without_ this bundle.

[Simperfit]

@fbourigault I think we should build a little bit of documentation about what you will need to build an API, basic HTTP principle and maybe people don't want to use a Bundle and to build it alone.

For those who talked about a symfony-demo app for building APIs, that's what ApiPlatform Standard Edition is doing.

[magarzon]

After years developing APIs REST with Symfony, from scratch, using the Form Component, then FOSRestBundle and now API Platform, I'd recommend to use API platform, but IMHO it has two "problems": hard learning curve for beginners and too much "Hydra centered" (Hydra is not suitable for all APIs, specially private ones used for M2M communication)

Anyway, the documentation should have the following topics:

• If you like DIY, don't use Form Component. Use Validator+Serializer component
• Authentication: How to use JWT Tokens
• Documentation: How to use Swager or Nelmio
• Routing: This depends on the bundle/framework used, but probably some reference to best practices naming routes in API REST
• Response: Serialization
• Errors: HTTP error codes to return in each case, and "standard" error responses, like API Platform and application/vnd.error+json
• Pagination, filtering, ...: Content-Range header, Link headers,...

[javiereguiluz]

I propose to close this issues because in all these years, nobody took the lead to contribute these docs. The good news is that things have changed a lot during this time. We now have ApiPlatform as a great project to create APIs in Symfony apps. The documentation of that project is the way to fix this issue. Thanks!