Cooking safety nests

Guillaume MOREL — Tue, 16 Feb 2021 14:09:43 +0000

Something still occurs too often:
Developers trying to conceal their mistakes 💣.

Most of the time it creates no particular issue. But sometimes it can lead to incident and even service outage.

This is a fact: developers often make mistakes. This is normal since nowadays technologies are highly complex.

In order to promote Teamplay we should embrace developer’s mistakes.

Because it is clearly unavoidable and this is the best way to learn.

Our responsibility however is to reduce any negative outcome. And to detect them ASAP when they are costless.

Nearly all mistakes will be noticed one way or another.
When they are noticed:

🎉 Ask for a homemade cookie !

Homemade 🍪 are a humorous way to de-escalate the way mistakes are perceived. Since developers no more fear being caught doing a mistake. It leads them to be way more transparent. Therefore it produces trust.

As soon as developers embrace mistakes. And as long as you provide them the tools/methodologies to reduce any negative outcome. You will create a safety nest. When your team members no more feel in danger, this reduces their cognitive load.

Another positive outcome is that developers will then openly share their mistakes. Allowing to transfer experience to other teammates. Hence mistakes won’t be done twice.

The last positive outcome is that now your developers will dare to take more initiatives. They will be less stunned by fear.

🍪 will ultimately increase your team productivity.

Working remotely ? Ask them to share the picture of their work. Or find a cheap alternative.

Another way for a Symfony API to ingest POST requests - No Bundle

Guillaume MOREL — Sun, 19 Jul 2020 15:34:18 +0000

Let's begin with some Behat:

Scenario: It creates a Product
  When I send a POST request to "/v1/products.json" with body:
  """
  {
    "id": "fabd5e92-02e7-43f7-a962-adab8ec88e94",
    "name": "Product1",
    "price": {
      "amount": 600,
      "currency": "EUR"
    }
  }
  """
  Then the response status code should be 201
  And the header "Location" should contain "/v1/products/fabd5e92-02e7-43f7-a962-adab8ec88e94.json"

There are several ways of building a RESTfull API in Symfony:

FOSRestBundle or API Platform
Custom by using the Form Component or using @ParamConverter
Or simply custom by extracting manually params one by one from a Request array

These are already proven to work great. But sometimes you just need a very simple way with minimum dependencies to ingest data from a Single Page Application or a Micro Service. Something pretty straight forward that will allow any intern/junior 🌱 to quickly be up to speed and autonomous in your project.

🎉 Meet the Serializer

private SerializerInterface $serializer;

// ...

/**
 * @Route("products.json", methods={"POST"})
 */
public function new(Request $request): JsonResponse
{
    /** @var CreateProductRequestPayload $requestPayload */
    $requestPayload = $this->serializer->deserialize(
        $request->getContent(),
        CreateProductRequestPayload::class,
        'json',
    );

    // Your Logic
}

Having a DTO request like this:

/**
 * DTO representing how API ingest JSON
 */
final class CreateProductRequestPayload
{
    public string $id;
    public string $name;
}

It uses the Symfony Serializer Component to deserialize a JSON into an Object.

Sorry to disappoint you ... but nothing new here: FOSRestBundle and API Platform are using it internally.

The good news is you have good chances to already have this component as a part of your project dependency.

If it is not already present:

composer require symfony/serializer

gmorel / very-light-symfony-api-example

Yet another Symfony API without Bundle

Full example here: https://github.com/gmorel/very-light-symfony-api-example/blob/master/src/Product/UI/Controller/ProductController.php#L38-L67

Validation

final class CreateProductRequestPayload
{
    /**
     * @Assert\NotNull
     * @Assert\Uuid
     */
    private string $id;

    /**
     * @Assert\NotNull
     * @Assert\NotBlank()
     */
    private string $name;

Exactly like you would do with Forms. You can now validate your $requestPayload against the Symfony Validator Component in the Controller.

$errors = $this->validator->validate($requestPayload);
if ($errors->count() > 0) {
    return new JsonResponse(
        $this->createErrorFromValidation($errors),
        Response::HTTP_BAD_REQUEST
    );
}

Deep validation

You can of course perform deep validation if your are using Value Objects:

Scenario: It fails to create a Product with bad amount and bad currency - Deep inspection:
  When I send a POST request to "/v1/en/products.json" with body:
  """
  {
    "id": "fabd5e92-02e7-43f7-a962-adab8ec88e94",
    "name": "Product 1",
    "price": {
      "amount": 0,
      "currency": "EU"
    }
  }
  """
  Then the response status code should be 400
  And the JSON node "type" should be equal to "UI Validation"
  And the JSON node "title" should be equal to "Bad Request"
  And the JSON node "violations" should have 2 elements
  And the JSON node "violations[0].propertyPath" should be equal to "price.amount"
  And the JSON node "violations[0].message" should be equal to "This value should be positive."
  And the JSON node "violations[1].propertyPath" should be equal to "price.currency"
  And the JSON node "violations[1].message" should be equal to "This value is not a valid currency."

⚠️ Don't forget the @Assert\Valid annotation.

/**
 * @Assert\Valid
 */
private PriceDTO $price;

Otherwise no deep validation will be performed. And without proper test suite you have good chance to notice it too late.

Bonus: i18n validation

You can have your JS/Mobile to directly show some already translated validation errors for free.

Scenario: It fails to create a Product in French
  When I send a POST request to "/v1/fr/products.json" with body:
  ...
  And the JSON node "violations[0].message" should be equal to "Cette valeur ne doit pas être vide."

For the simplicity of the example locale is set in the URL. But I would advise to have the locale extracted from HTTP Headers. So user Browser/Phone could take care of the locale by itself.

Given I add "Accept-Language" header equal to "fr"

Mixing ParamConverter + Serializer

You could also mix ParamConverter + Serializer 🚀. This is clever. However Listeners tend to confuse new comers and juniors. Use them wisely as they bring their own complexity.

OpenAPI documentation - Swagger

You can still generate an OpenAPI documentation by adding the relevant annotations to your RequestPayload using SwaggerPHP or via NelmioApiDocBundle v4.

Wait a little: CreateProductRequestPayload has only public properties. Where is our user intention's immutability here ?
I let you read this and then decide by yourself. You might also want to try Psalm.

DEV Community: Guillaume MOREL