Creating your First ApiResource

Edit on GitHub

We're about to build an API for the very important job of allowing dragons to show off their treasure. Right now, our project doesn't have a single database entity... but we're going to need one to store all that treasure.

Generating our First Entity

Find your terminal and first run

composer require maker --dev

to install Maker Bundle. Then run:

php bin/console make:entity

Perfect! Let's call our entity DragonTreasure. Then it asks us a question that you maybe haven't seen before - Mark this class as an API platform resource? It asks because API Platform is installed. Say no because we're going to do this step manually in a moment.

Okay, let's start adding properties. Start with name as a string, with a Length of the default 255, and make it not nullable. Then, add description with a text type, and make that not nullable. We also need a value, like... how much the treasure is worth. That will be an integer not nullable. And we simply must have a coolFactor: dragons need to specify just how awesome this treasure is. That'll be a number from 1 to 10, so make it an integer and not nullable. Then, createdAt datetime_immutable that's not nullable... and Finally, add an isPublished property, which will be a boolean type, also not nullable. Hit " enter" to finish.

Phew! There's nothing very special so far. This created two classes: DragonTreasureRepository (which we're not going to worry about), and the DragonTreasure entity itself with $id, $name, $description, $value, etc

            
            112 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 2
                            
            namespace App\Entity;
        
            use App\Repository\DragonTreasureRepository;
        
            use Doctrine\DBAL\Types\Types;
        
            use Doctrine\ORM\Mapping as ORM;
        
            #[ORM\Entity(repositoryClass: DragonTreasureRepository::class)]
        
            class DragonTreasure
        
            {
        
                #[ORM\Id]
        
                #[ORM\GeneratedValue]
        
                #[ORM\Column]
        
                private ?int $id = null;
        
                #[ORM\Column(length: 255)]
        
                private ?string $name = null;
        
                #[ORM\Column(type: Types::TEXT)]
        
                private ?string $description = null;
        
                #[ORM\Column]
        
                private ?int $value = null;
        
                #[ORM\Column]
        
                private ?int $coolFactor = null;
        
                #[ORM\Column]
        
                private ?\DateTimeImmutable $plunderedAt = null;
        
                #[ORM\Column]
        
                private ?bool $isPublished = null;
        
                                                    ... lines 35 - 110
                            
            }

along with the getter and setter methods. Beautifully boring. There is one little bug in this version of MakerBundle, though. It generated an isIsPublished() method. Let's change that to getIsPublished().

            
            112 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 9
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 12 - 99
                            
                public function getIsPublished(): ?bool
        
                {
        
                    return $this->isPublished;
        
                }
        
                public function setIsPublished(bool $isPublished): self
        
                {
        
                                                    ... lines 107 - 109
                            
                }
        
            }

Setting up the Database

All right, so we have our entity. Now we need a migration for its table... but that might be a bit difficult since we don't have our database set up yet! I'm going to use Docker for this. The DoctrineBundle recipe gave us a nice docker-compose.yml file that boots up Postgres, so... let's use that! Spin over to your terminal and run:

Tip

In modern versions of Docker, run docker compose up -d instead of docker-compose.

docker-compose up -d

If you don't want to use Docker, feel free to start your own database engine and then, in .env or .env.local, configure DATABASE_URL. Because I'm using Docker as well as the symfony binary, I don't need to configure anything. The Symfony web server will automatically see the Docker database and set the DATABASE_URL environment variable for me.

Okay, to make the migration, run:

symfony console make:migration

This symfony console is just like ./bin/console except it injects the DATABASE_URL environment variable so that the command can talk to the Docker database. Perfect! Spin over and check out the new migration file... just to make sure it doesn't contain any weird surprises.

            
            36 lines
            
            migrations/Version20230104160057.php
        
                                                    ... lines 1 - 4
                            
            namespace DoctrineMigrations;
        
            use Doctrine\DBAL\Schema\Schema;
        
            use Doctrine\Migrations\AbstractMigration;
        
            /**
        
             * Auto-generated Migration: Please modify to your needs!
        
             */
        
            final class Version20230104160057 extends AbstractMigration
        
            {
        
                                                    ... lines 15 - 19
                            
                public function up(Schema $schema): void
        
                {
        
                    // this up() migration is auto-generated, please modify it to your needs
        
                    $this->addSql('CREATE SEQUENCE dragon_treasure_id_seq INCREMENT BY 1 MINVALUE 1 START 1');
        
                    $this->addSql('CREATE TABLE dragon_treasure (id INT NOT NULL, name VARCHAR(255) NOT NULL, description TEXT NOT NULL, value INT NOT NULL, cool_factor INT NOT NULL, plundered_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL, is_published BOOLEAN NOT NULL, PRIMARY KEY(id))');
        
                    $this->addSql('COMMENT ON COLUMN dragon_treasure.plundered_at IS \'(DC2Type:datetime_immutable)\'');
        
                }
        
                public function down(Schema $schema): void
        
                {
        
                    // this down() migration is auto-generated, please modify it to your needs
        
                    $this->addSql('CREATE SCHEMA public');
        
                    $this->addSql('DROP SEQUENCE dragon_treasure_id_seq CASCADE');
        
                    $this->addSql('DROP TABLE dragon_treasure');
        
                }
        
            }

Looks good! So spin back over and run this with:

symfony console doctrine:migrations:migrate

Done!

Exposing our First API Resource

We now have an entity and a database table. But if you go and refresh the documentation... there's still nothing there. What we need to do is tell API Platform to expose our DragonTreasure entity as an API resource. To do this, go above the class and add a new attribute called ApiResource. Hit "tab" to add that use statement.

            
            114 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 4
                            
            use ApiPlatform\Metadata\ApiResource;
        
                                                    ... lines 6 - 9
                            
            #[ORM\Entity(repositoryClass: DragonTreasureRepository::class)]
        
            #[ApiResource]
        
            class DragonTreasure
        
            {
        
                                                    ... lines 14 - 112
                            
            }

Done! As soon as we do that... and refresh... whoa! The documentation is alive! It now shows that we have six different endpoints: One to retrieve all of the DragonTreasure resources, one to retrieve an individual DragonTreasure, one to create a DragonTreasure, two that edit a DragonTreasure plus one to delete it. And this is more than just documentation. These endpoints work.

Go over and click "Try it Out", then "Execute". It doesn't actually return anything because our database is empty, but it does gives us a 200 status code with some empty JSON. We'll talk about all of the other fancy keys in the response shortly.

Oh, but I do want to mention one thing. As we just saw, the easiest way to create a set of API endpoints is by adding this ApiResource attribute above your entity class. But you can actually add this attribute above any class: not just entities. That's something we're going to talk about in a future tutorial: it can be a nice way to separate what your API looks like from what your entity looks like, especially in bigger APIs. But again, that's for later. Right now, using ApiResource on top of our entity is going to work great.

Let's discover this cool, interactive documentation a bit more. Where did this come from? How does our app magically have a bunch of new routes? And do dragons really love tacos? Let's find out next!

Leave a comment!

Szymon | posted 7 months ago

Hello,

When I run symfony console make:migration then:

[critical] Error thrown while running command "make:migration". Message: "An exception occurred in the driver: could not find driver"

In ExceptionConverter.php line 87:

  An exception occurred in the driver: could not find driver


In Exception.php line 28:

  could not find driver


In Driver.php line 34:

  could not find driver

How to fix it? I am working with PHP8.2 and Symfony6...

1 Reply

weaverryan | SFCASTS | Szymon | posted 7 months ago

Hey Szymon!

I know this error! If you're using the code from the course, then we're using Postgres. The error means that you need to install the pgsql php extension - e.g. like described here (the exact setup instructions will depend on your operating system): https://stackoverflow.com/questions/10085039/postgresql-pdoexception-with-message-could-not-find-driver#answer-48858539

Or, if you'd rather use Mysql, you can skip the migrations and run doctrine:schema:update --force instead (after configuring your app to talk to your mysql database).

Let me know if this helps!

Cheers!

4 Reply

Szymon | weaverryan | posted 7 months ago | edited

yeah, that's right. I am using Windows, and I just removed semicolon in xampp/php/php.ini

extension=pdo_pgsql
...
extension=pgsql

and it's running good.

But it's kind weird for me, because I am not using XAMPP, I installed php directly in my computer, but most important is that working anyway :)

additional query: what is the difference between using MySQL and PostgreSQL in this tutorial? I remember in Symfony5 tutorial we used MySQL.
Is chance to see this database tables in friendly environemnt like phpMyAdmin or something similar? does it require a more difficult setup?

1 Reply

MolloKhan | SFCASTS | Szymon | posted 7 months ago

Hey Szymon,

In this tutorial, the only difference you'll find if you use MySQL instead of PostgreSQL is the migration files. The queries generated by Doctrine will be specific to MySQL, but besides that, nothing else will be different.

Is chance to see this database tables in friendly environemnt like phpMyAdmin or something similar? does it require a more difficult setup?

I found this tool for Postgres. However, I don't know how hard it might be to set it up. https://github.com/phppgadmin/phppgadmin

Cheers!

Ken | posted 3 months ago

Are there anyway to create custom API such as api/hello-world without entity

MolloKhan | SFCASTS | Ken | posted 3 months ago | edited

Hey @Ken

Yes, APIPlatform does not force you to create entities for your resources, you can do the exact same thing with data model classes
Here are the docs: https://api-platform.com/docs/core/dto/#using-data-transfer-objects-dtos

Cheers!

Yorane | posted 3 months ago

Hi !

Thanks for the tutorial :)
I have some trouble about the symfony console make:migration part.
Without modifing docker-compose.ymlfile, when I try to apply the migrations (after boot the container with docker compose up -d) i get the next error :

SQLSTATE[08006] [7] connection to server at "127.0.0.1", port 5432 failed: Connection refused
    Is the server running on that host and accepting TCP/IP connections?

Do you have a solution ?
For information, I'm working on Windows with WSL.

Thank you !

MolloKhan | SFCASTS | Yorane | posted 3 months ago | edited

Hey @Yorane

I'm afraid I cannot help you with your Docker setup because I don't use it under WSL, but I have a question, does it only happens when you try to load the migrations?

Yorane | MolloKhan | posted 3 months ago

Hi MolloKhan,

It's OK, I resolved my problem :)
Not only, every time my server try to connect to the container database.

To resolve the problem, we have to change the IP address in the .envfile with the container IP.

1 Reply

MolloKhan | SFCASTS | Yorane | posted 3 months ago | edited

Oh cool, well done @Yorane
Tip: when you use Docker, you need to run any command through the Symfony CLI, so it can inject the correct env var values
symfony console app:foo

Cheers!

Kev | posted 4 months ago | edited

Hey i always get this

500
Undocumented
Error: Internal Server Error.

This is my docker-compose.yaml regarding the mysql container

database:
    container_name: database
    image: mysql
    command: --default-authentication-plugin=mysql_native_password
    environment:
      MYSQL_ROOT_PASSWORD: dsv
      MYSQL_DATABASE: dsv_db
      MYSQL_USER: dsv
      MYSQL_PASSWORD: dsv
    ports:
      - '4306:3306'
      #to avoid lower versions/ or existing install / conflicts
      # this volume will create new mysql8 folder
    volumes:
      - ./mysql:/var/lib/mysql``

and my .env

DATABASE_URL="mysql://app:!ChangeMe!@127.0.0.1:3306/app?serverVersion=8&charset=utf8mb4"

and response body:

{
  "@context": "/api/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "An exception occurred in the driver: could not find driver",
  "trace": [

... more log below

I am sure i have the drivers i need but..any suggestion would be welcomed. Thank you!

weaverryan | SFCASTS | Kev | posted 4 months ago

Hey @Kev!

Well that's annoying! You're using Mysql, so the "could not find driver" is referring to the PHP pdo_mysql driver. Exactly HOW you install this depends on your system - e.g. with Ubuntu, it's often something like apt install php-mysql. Also, remember to restart your web server (e.g. the symfony binary) after installing the driver. And FINALLY. if you have multiple php binaries installed and you're not sure which one the symfony binary is using, you can always run symfony local:php:list to find out.

Cheers!

1 Reply

Kev | weaverryan | posted 4 months ago | edited

Hey @weaverryan ,

Thanks for your answer, the general idea is that i already have the php-mysql driver installed. I have it as a docker-compose procedure script for a container, AND i have it on my local ubuntu machine installed.

The default .env build with the default postrgres variable is the same result.

Weirdish issue really!

Cheers!

weaverryan | SFCASTS | Kev | posted 3 months ago

That IS weird. That usually means that some different, unexpected PHP binary is being used (that doesn't have the driver installed).... but these are a pain to figure out!

1 Reply

Symfony 6.2 API Platform 3.0

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^3.0", // v3.0.8
        "doctrine/annotations": "^1.0", // 1.14.2
        "doctrine/doctrine-bundle": "^2.8", // 2.8.0
        "doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.2
        "doctrine/orm": "^2.14", // 2.14.0
        "nelmio/cors-bundle": "^2.2", // 2.2.0
        "nesbot/carbon": "^2.64", // 2.64.1
        "phpdocumentor/reflection-docblock": "^5.3", // 5.3.0
        "phpstan/phpdoc-parser": "^1.15", // 1.15.3
        "symfony/asset": "6.2.*", // v6.2.0
        "symfony/console": "6.2.*", // v6.2.3
        "symfony/dotenv": "6.2.*", // v6.2.0
        "symfony/expression-language": "6.2.*", // v6.2.2
        "symfony/flex": "^2", // v2.2.4
        "symfony/framework-bundle": "6.2.*", // v6.2.3
        "symfony/property-access": "6.2.*", // v6.2.3
        "symfony/property-info": "6.2.*", // v6.2.3
        "symfony/runtime": "6.2.*", // v6.2.0
        "symfony/security-bundle": "6.2.*", // v6.2.3
        "symfony/serializer": "6.2.*", // v6.2.3
        "symfony/twig-bundle": "6.2.*", // v6.2.3
        "symfony/ux-react": "^2.6", // v2.6.1
        "symfony/validator": "6.2.*", // v6.2.3
        "symfony/webpack-encore-bundle": "^1.16", // v1.16.0
        "symfony/yaml": "6.2.*" // v6.2.2
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.2
        "symfony/debug-bundle": "6.2.*", // v6.2.1
        "symfony/maker-bundle": "^1.48", // v1.48.0
        "symfony/monolog-bundle": "^3.0", // v3.8.0
        "symfony/stopwatch": "6.2.*", // v6.2.0
        "symfony/web-profiler-bundle": "6.2.*", // v6.2.4
        "zenstruck/foundry": "^1.26" // v1.26.0
    }
}

Edit on GitHub

TRACK

APIs >

COURSE

API Platform 3 Part 1: Mythically Good RESTful APIs

Creating your First ApiResource

Video not working?

Generating our First Entity

Setting up the Database

Exposing our First API Resource

Leave a comment!

What PHP libraries does this tutorial use?

	... lines 1 - 2
	namespace App\Entity;

	use App\Repository\DragonTreasureRepository;
	use Doctrine\DBAL\Types\Types;
	use Doctrine\ORM\Mapping as ORM;

	#[ORM\Entity(repositoryClass: DragonTreasureRepository::class)]
	class DragonTreasure
	{
	#[ORM\Id]
	#[ORM\GeneratedValue]
	#[ORM\Column]
	private ?int $id = null;

	#[ORM\Column(length: 255)]
	private ?string $name = null;

	#[ORM\Column(type: Types::TEXT)]
	private ?string $description = null;

	#[ORM\Column]
	private ?int $value = null;

	#[ORM\Column]
	private ?int $coolFactor = null;

	#[ORM\Column]
	private ?\DateTimeImmutable $plunderedAt = null;

	#[ORM\Column]
	private ?bool $isPublished = null;

	... lines 35 - 110
	}

	... lines 1 - 9
	class DragonTreasure
	{
	... lines 12 - 99
	public function getIsPublished(): ?bool
	{
	return $this->isPublished;
	}

	public function setIsPublished(bool $isPublished): self
	{
	... lines 107 - 109
	}
	}

	... lines 1 - 4
	namespace DoctrineMigrations;

	use Doctrine\DBAL\Schema\Schema;
	use Doctrine\Migrations\AbstractMigration;

	/**
	* Auto-generated Migration: Please modify to your needs!
	*/
	final class Version20230104160057 extends AbstractMigration
	{
	... lines 15 - 19
	public function up(Schema $schema): void
	{
	// this up() migration is auto-generated, please modify it to your needs
	$this->addSql('CREATE SEQUENCE dragon_treasure_id_seq INCREMENT BY 1 MINVALUE 1 START 1');
	$this->addSql('CREATE TABLE dragon_treasure (id INT NOT NULL, name VARCHAR(255) NOT NULL, description TEXT NOT NULL, value INT NOT NULL, cool_factor INT NOT NULL, plundered_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL, is_published BOOLEAN NOT NULL, PRIMARY KEY(id))');
	$this->addSql('COMMENT ON COLUMN dragon_treasure.plundered_at IS \'(DC2Type:datetime_immutable)\'');
	}

	public function down(Schema $schema): void
	{
	// this down() migration is auto-generated, please modify it to your needs
	$this->addSql('CREATE SCHEMA public');
	$this->addSql('DROP SEQUENCE dragon_treasure_id_seq CASCADE');
	$this->addSql('DROP TABLE dragon_treasure');
	}
	}

	... lines 1 - 4
	use ApiPlatform\Metadata\ApiResource;
	... lines 6 - 9
	#[ORM\Entity(repositoryClass: DragonTreasureRepository::class)]
	#[ApiResource]
	class DragonTreasure
	{
	... lines 14 - 112
	}