MetaClass' Tutorial API Platform

API Platform is quite well documented, but the documentation is stuctured according to the components and features of api-platform, not to the tasks of building an actual application. This tutorial takes you step by step through the process of building a simple application with api platform and the react or next.js client generator. Simple generic and example Components are factored out to keep the application DRY and clearly arranged.

Chapters and branches

Employee base api react next
Hours registration api react next
Localization and Internationalization api react next
Labels and Entity Select api react next
Search api react
Sorting and Custom Filter api react
Authentication (JWT) api react
Authorization api react
Report api react
End api react

Each chapter has one 'api' branch in git, one 'react' branch and some also a 'next' branch. The 'api' branches only contain api code, the 'react' and 'next' branches contain both api code and react/next code. If you are only interested in the api side you can skip the react and next branches. The api branches only use the Swagger UI and curl for testing and do not depend on react or next.

Each branch builds on top of the previous one of the same type. Each client branch also contains the code from the corresponding 'api' branch. To see the code resulting from a branch you can check out the next branch of the same type, or browse it on github. Or better: let git compare your current code with the branch of the next chapter so that you can see the differences right away.

In addition to this tutorial an extended client generator for react and next.js is available that puts what you have learnt into use for scaffolding your own application.

This tutorial has next.js branches and an extended client generator for the first 4 chapters only. It also contains examples of an angular client for chapter1 and chapter 3 but no instructions.

Required knowledge

maybe docker and docker compose APi branches:
PHP 7 or 8
Symfony 5
Doctrine ORM React branches:
ES6
React.js
Redux
React Router Next branches:
ES6
Next.js
React.js Angular example branches:
ES6
Angular.io

You don't need to be an expert in these domains, having folowed the tutorials of the suppliers should be enough.

Requirements

The master branch that was checked out when cloning the repository contains an allmost unmodified (1) Api Platform Distribution. You need Docker (recent version with docker compose) to run it. On Mac, only Docker for Mac is supported. Similarly, on Windows, only Docker for Windows is supported. Docker Machine is not supported out of the box.

(1) README.md was changed obviously and tutorial branches where added. To sustain the original order of the doctrine migrations Version20200828181711 was replaced by Version20190819120152 from a previous version of API Platform.

Install

Clone the tutorials repository using git:

git clone https://github.com/metaclass-nl/tutorial-api-platform.git

Testing your install

You may test the installation following the instructions on the api platform website. Just skip the part about downloading and extracting the .tar.gz file and go straight to:

cd tutorial-api-platform
docker compose pull # Download the latest versions of the pre-built images
docker compose up

As we did not install using Symfony Flex and Composer you can skip that section and go straight to It's Ready!. Follow the instructions to test the api.

To test the admin interface point your browser at https://localhost/admin.

Getting Started

To start at the beginning check out branch chapter1-api and point your browser to the same branch on github to get a nicely rendered version of its readme. When you are finished with the instructions you commit your changes and check out a client branch: chapter1-react or chapter1-next, select it in your browser as well, etc. Then follows chapter2-api, chapter2-react etc.
If you only want to do the api branches you can skip the client ones.

But you can start with any branch by checking it out and following its instructions. However, if you skip a chapter you need to restart docker compose to apply the migrations. Then apply the DataFixtures by:

docker compose exec php bin/console doctrine:fixtures:load

For a next branch you may also need to update pnpm:

docker compose exec pwa pnpm install

Wait for yarn or pnpm to complete, then (for next replace client by pwa):

docker compose exec pwa pnpm update

For a react branch you may also need to update npm:

docker compose exec pwa npm install

Wait for yarn or npm to complete, then:

docker compose exec client npm update

With chapter 4 react/next and higher if you still get an error on missing react-intl, you may need to add react-intl

About the admin interface

Api platform is a very powerfull framework, but i's aproach to application development (if you use doctrine or ElasticSearch) is still revolutionary: Instead of developing your own controllers, services and a user interface on top of an existing framework, you only supply the domain classes (Entities) and some configuration and the framework supplies default behavior for the api. Then you then you adapt (decorate, extend, override) it to suit your needs.

With proper training this approach gives high productivity and great flexibility, but is tends to have a steep leaning curve. Api platform is quite well documented, but the documentation is stuctured according to the components and features of api-platform, not to the tasks of building an actual application.

The tutorial contains instructions with respect to the scaffolded React 'client' user interface. The scaffolded React 'client' user interface is simple and insightfull as all the code for the basic CRUD operations is generated as-expected, understanding and adapting it just requires common knowledge of ES6, react and redux and will add to your general experience with them.

The 'admin' user interface is based on the abstact user interface React Admin. Experience with phpPeanuts learns that an abstract user interface add considerably to the steepness of the learning curve. Furthermore you will learn mostly about the specifics of React Admin, and less about building common applications with ES6, react and redux.

This doesn't mean the admin user interface is not interesting, it is! But for a smaller audience of more experienced developers who want to get the most out of api platform. Therefore branches for the 'admin' user interface are left out for now.

Limitations

This is a work in progess and needs more testing.

This tutorial currently only supports the api core, the (scaffolded) React client user interface and some chapters about the (scaffolded) Next.js client user interface. The angular.io branches only contain code and no instructions for its development.

The react client uses the older version (v0.7.3) of the client generator that does not generate typescript but plain ES6. The next.js client generator uses a newer version (v0.10.0).

This distribuition is only for educational purposes and will not be updated frequently. If you want to run a client container for react or angular within the standard distribution of api platform you are advised to create your own fork and add a similar container there yourself. You will need to keep your fork up to date yourself. For most of it you can pull updates from Api Platform, but they will not supply updates for your client container, you will need to maintain it yourself, especially its package.json. You also need to maintain yourself any generated code as well as any components from the tutorial that you use. Old software versions are prone to have known security vurnerabilities but new versions need to be tested with your application before use in production.

Credits

The tutorial and examples are copyright (c) MetaClass , Groningen, 2019-2021. MetaClass offers software development and support in the Netherlands for Symfony, API Platform, React.js and Next.js

The tutorial is based the Api Platform Distribution and Api Platform core version 3.0, created by Kévin Dunglas.

Contribution

Ideas and bug reports are welcome.

Please fork the repository and add tutorial branches there for some other client (generation) platform or the admin component, then send a merge request.

However, api platform and the client platforms are changing constantly. Even though the tutorial is for educational purposes only, at some point you may need to update your branches to keep them up to date and working. Please do not request the merging of code that you are not willing to maintain. Abandoned branches that are no longer functional or have security issues may be removed.

When you open a Pull Request to this repository, you agree to license the (changes to the) code that is subject to the pull request under the MIT license.

metaclass-nl / tutorial-api-platform