API Platform: Serious RESTful APIs

2:54:11

What you'll be learning

API Platform is crushing the scene these days. And it's easy to see why! Built on top of Symfony, API Platform enables you to build a rich, JSON-LD-powered, hypermedia API... pretty much instantly! In this tutorial, we'll build a real app and leverage these tools:

  • Setting up API Platform in a Symfony app
  • Swagger, OpenAPI & JSON-LD+Hydra: what they are and why they're awesome
  • Creating ApiResources
  • Customizing the operations
  • IRIs & how to control them
  • Resource relations
  • Embedded resources & Subresources
  • Filters
  • Pagination
  • Validation
  • The serializer & controlling input/output fields

Your Guides

Niels van der Molen Ryan Weaver

Buy Access

Questions? Conversation?

  • 2020-06-09 Jhioui Soufiane

    Hi @waeverryan
    Thank you for your reply, it's really a great help for me.
    I will definitly give it a try and let you know abouti it.

    Thank's for this great work.

  • 2020-06-08 weaverryan

    Hi Jhioui Soufiane!

    Welcome to the nice world of API Platform :).

    > 1 - Is api Platform suitable for making microservices ?

    Sure! It makes creating APIs quick and easy - I don't see any problem here.

    > My matter is i have an openapi specs and i want to generate php classes to handle the request. The request will probably make crud operations of many entities and not only one so i can't just diretly use doctrine models. how do i i handle this bestens

    It sounds to me like you would want to create custom "model classes" for your API resources. This is not something we cover in our tutorial, but it's a fairly common use-case. Basically, instead of adding @ApiResource to an entity, you would create a class in the src/Entity/ directory (you could put it somewhere else, you would just need to update some API Platform config to look in the new directory), NOT make this class an entity, and then add @ApiResource to THIS class. You would then design this class to match your OpenAPI spec exactly: this gives you the power to design your API like you need, even if it looks quite different than your database entities. Finally, in order for API Platform to know how to fetch and persist data for your non-entity class, you will need to create a custom "data persister" - example https://symfonycasts.com/sc... - and a custom "data provider" - https://api-platform.com/do...

    Let me know if that helps :).

    > 2 - Is there a tool you suggest to auto generate symfony / doctrine classes from openapi specs to use it with api platform ?

    I do not think that there is. In your case, since you said that your OpenAPI spec looks quite different than your database entities would probably look, you wouldn't want to generate "entities" from your OpenAPI spec anyways: you really want to create non-entity classes that match exactly. And I don't think there is a way to generate in this direction. The reason is that API Platform is kind of meant to be used in the *other* direction: you create the ApiResource classes and customize them, and then ApiPlatform *generates* the OpenAPI document based on your classes. In your case, I think you would need to create the classes by hand, then customize them until the OpenAPI document generated by API Platform matches the one you have currently.

    Cheers!

  • 2020-06-08 Jhioui Soufiane

    Hello Everybody,
    I am new with api platform and i find it's a great framework to make Rest APIs. I have some questions :
    1 - Is api Platform suitable for making microservices ? My matter is i have an openapi specs and i want to generate php classes to handle the request. The request will probably make crud operations of many entities and not only one so i can't just diretly use doctrine models. how do i i handle this bestens ?
    2 - Is there a tool you suggest to auto generate symfony / doctrine classes from openapi specs to use it with api platform ?

    Thanks in advance.

  • 2020-06-01 Jhioui Soufiane

    Hi weaverryan
    Thanks for the reply. I will give the tool you suggest a try and see the result. As you said it's just fine if i get a set of "nearly correct" entity classes that will be a nice start.
    Cheers !

  • 2020-05-31 weaverryan

    Hey Jhioui Soufiane !

    > First of all thanks fir this great tutorial

    Cheers! And welcome :).

    > How to generate Api Models from an existing database. It mut be a lot of Symfony tools to do this.

    What you *really* want to do is generating a set of Doctrine entity classes from your existing database. Once you have done this, you only need to add the @ApiResource annotation to convert the entity class into an API resource.

    The tool to do this is here: https://symfony.com/doc/cur... - it's not perfect (well, it will do a perfect job if your database is "perfect" and "normalized", but not a perfect job if your database has some "weirdness"), but it should give you a set of "nearly correct" entity classes. You can then "tweak" the @ORM\ annotations to (hopefully) make it perfect. The goal would be that you are able to run php bin/console doctrine:schema:update --dump-sql and this returns NO sql. This would mean that your Doctrine entities "match" your database structure perfectly. Then add @ApiResource to each entity and you're good!

    How well this will work (or not work) depends on how normalized your existing database is. Doctrine likes databases to be "neat" and "normalized", You can make Doctrine work with a very non-normalized database, but it requires more setup work.

    Cheers!

  • 2020-05-31 Jhioui Soufiane

    Hello,
    First of all thanks fir this great tutorial ; it's really interesting and forgive my poor English...
    So, i try to start with Api Platform and my first question is How to generate Api Models from an existing database. It mut be a lot of Symfony tools to do this. Is there any one that you suggest ? a Tutorial for this maybe ?
    thanks in advance.

  • 2020-04-17 weaverryan

    Hey mostwanted!

    > This course "only" covers CRUD operations, right

    Haha, yes. That's not exactly on purpose - it's a product of REST - REST fits most "cleanly" for CRUD operations and API Platform is all about REST. On a philosophical level, we talk about these in an older tutorial - https://symfonycasts.com/sc... and the chapter after that :).

    So, the first thing to figure out is how you want to implement this simply from an HTTP perspective (not thinking about API Platform). Sometimes these things just *aren't* very RESTful. That's not idea... but you still gotta get your work done at the end of the day. For example, I might decide to:

    – HoldDealUseCase(id, reason); - POST /api/deals/{id}/status with { hold: true }
    – UnholdDealUseCase(id); POST /api/deals/{id}/status with { hold: false }
    – CompleteDealUseCase(id, and many another params); POST /api/deals/{id}/complete with { params } OR maybe you consider this the creation of a new "completed deal" resource, in which case it would be POST /api/completed-deal where the "deal" is in the JSON
    ...
    – ChangePriceUseCase(id, newPrice, reason); PUT /api/deals/{id} and you send "price" and "reason" as fields. This may or may not work if you need to force the new price change to always have a reason. You might also consider that this is the creation of a new "price change" reason - in which case, you might have POST /api/price-change or by leveraging a sub-resource, you could tweak the URK to POST /api/deals/{id}/price-change
    ...

    For several of these, I listed multiple possible solutions. And each solution would be implemented differently. Some of the solutions DO fit just fine into CRUD. For the others, you have a few options. And this is all stuff that we're planning to cover in our next episode of this tutorial. Options include:

    * A DTO API resource
    * Symfony Messenger integration
    * Last resort, a custom controller/action

    You might also like this open documentation issue: https://github.com/api-plat...

    Let me know if that helps!

    Cheers!

  • 2020-04-14 mostwanted

    This course "only" covers CRUD operations, right? Is it possible/wise to use API Platform if you plan to design an API that supports non-CRUD operations? You can find some examples in this question on Stackoverflow: https://stackoverflow.com/q...


    But what to do with the rest of the use cases?

    – HoldDealUseCase(id, reason);
    – UnholdDealUseCase(id);
    – CompleteDealUseCase(id, and many another params);
    – CancelDealUseCase(id, amercement, reason);
    – ChangePriceUseCase(id, newPrice, reason);
    – ChangeCompletionDateUseCase(id, newDate, amercement, whyChanged);
    – etc. (total 20 use cases)...
  • 2020-01-17 ebelair

    Thank you very much for checked it!

  • 2020-01-17 Victor Bocharsky

    Hey Evelair,

    I just double-checked it for you: downloaded the course code and checked the installed version of API Platform in composer.lock - "api-platform/core" package is locked on v2.4.3. The latest is 2.5.4, but I remember we added some notes in this course according to some changes that were done in 2.5 minor release.

    I hope this helps!

    Cheers!

  • 2020-01-16 ebelair

    What api-platform version is this podcast about?

  • 2020-01-05 cybernet2u

    Thank you !

  • 2019-09-20 Diego Aguiar

    Oh, yes, in this course there is some Vue.js code but that's not the topic of it. That's way most of the things are handled via tests. But, we will take your comment as a request for a ReactJS course powered with ApiPlatform

    Cheers!

  • 2019-09-20 Seba Stien

    Hey Diego Aguiar,
    But it's only with test, not in front.
    You know what I mean ?

  • 2019-09-10 weaverryan

    Hey Isaac Earl!

    We will in the next tutorial :). That will be a bit more about customizations, including custom operations and DTO's.

    Cheers!

  • 2019-09-07 Isaac Earl

    I'm hoping you'll add a lesson about transformers (dtos)

  • 2019-08-23 Diego Aguiar

    The new course is focused on security but in this course, Ryan creates 2 Api resources and basically plays with all the operations.

  • 2019-08-23 Sébastien JEAN

    Hey Diego Aguiar ,
    Thank you for your answer.
    In the new course, there is CRUD?

  • 2019-08-13 Diego Aguiar

    Hey Sébastien JEAN

    We are actively releasing a new course about Api Platform + Symfony + Vue.js. I know it's not ReactJS but its internals are very similar
    https://symfonycasts.com/sc...

    Cheers!

  • 2019-08-13 Sébastien JEAN

    Hey,
    Are you planning to release a course with API Platform and ReactJS ?

  • 2019-07-03 weaverryan

    Wow, nice work Kiss Dávid! Thanks for sharing - I was interested if this was ultimately going to work - very cool.

  • 2019-07-03 Kiss Dávid

    Thank you for your answer and sorry for my late reaction, i was lost in space. :D
    During this time, i found a solution for my 'challenge :)' The following two posts helped me to handle the custom URLs: post 1 and Post 2. I had to modify some methods to handle the account id dynamically. In the close future i will add URL or IRI generator class(es) to handle the sub-sub URLs (similar to sub-sub-resources). Besides in my case i had to add a custom data provider, due to the usage of the account id. Fortunately i could add the APIP-way pagination, filtering and searching support to custom data providers. (The ODM way wasn't clear at the first look. :) )

  • 2019-06-26 weaverryan

    Hey Vladimir Light!

    Interesting idea... it's not currently on my list to cover for the next "security" tutorial... because they're kinda two separate things. But, I've upvoted this in our internal idea list - it's something that we *may* cover, but I don't have any timing yet.

    Cheers!

  • 2019-06-20 weaverryan

    Hey Kiss Dávid!

    Thanks for the nice words! And yes, we'll get to the custom controller stuff... API stuff is such a huge topic - we need a few parts :).

    About your questions... I don't think there's good news here. As you maybe already saw, this isn't supported currently (https://github.com/api-plat....... which means you'll need to add this stuff manually. That's not a total loss... you'll still be able to rely on API Platform's serialization/deserialization stuff, validation, security, etc. There *may* be some more clever way to make this all work.. but I haven't played with it yet. For example, in "theory" (big quotes... as I've tried none of this!), you could do this by filling in a few pieces. Basically, the goal would be customize things so that Store could be a normal ApiResource, which just has this custom URL:

    1) customize the URL of each operation in Store (I think this needs to be done for each individual operation)
    2) To make the above work, I think you will need a getAccountId() method inside Store, so that API platform knows what to use for the account_id part in the IRI when generating it.
    3) You may also need a custom data provider so that you can use the account_id in a custom query to return all of the stores.

    And... probably there are 5 other small details - I really don't know, unfortunately. But, for me, it would be worth trying to see if you can get the above to work, as it would ultimately allow you to use ApiPlatform in a "normal" way, instead of needing to make a lot of custom endpoints.

    Let me know what you find out!

    Cheers!

  • 2019-06-19 weaverryan

    Yep! Sorry about that! The tutorials tend to evolve as we write them :). In this case, there was too much to cover in part one - but it's still planned for the future.

    Cheers!

  • 2019-06-19 Kiss Dávid

    Hey weaverryan !
    First of all i'd like to thanks your tutorials, i really like those and are really helpful.
    I agree with Gabriel's post, APIP is really good, but now i have a problem with custom URLs. My goal is to use a url scheme, where the first 2 parameters reference to account and account id, and most of the URLs contain it. The following parameters are store, products and so on. e.g.: /account/account_id/stores or /account/account_id/store/store_id/products...
    The sub-resources would be good, but unfortunately it supports GET operation only. I try to find a proper solution for my problem, but i haven't found it yet. I hope you can give me some starter points how i can manage this URL structure.
    Thanks in advance!

  • 2019-06-19 Victor Bocharsky

    Hey Br!

    Good news for you - we're going to cover GraphQL topic as well, but we will do it in further episodes. This is a big topic and we wanted to make a separate episode for this.

    Cheers!

  • 2019-06-18 Br

    Why did you change the name from "API Platform: Serious RESTful & GraphQL API" to "API Platform: Serious RESTful APIs"? :(
    I was waiting for the GraphQL part the most.

  • 2019-06-17 Gabriel Mustiere

    Yes, I know about this feature, Kevin talked about it in a twitter conversation -> https://twitter.com/MrConsp..., it's still a little obscure and not very intuitive to implement, "just for a simple endpoint", Thks

  • 2019-06-17 weaverryan

    Hey Gabriel Mustiere!

    I agree 💯! We will cover it, but not in this tutorial. And yes, the docs are a bit confusing on this topic, as the "best" way to do it is kinda changing... I'm talking to Kevin about this. So, we will get there - but not until probably part 3 (part 2 will all be about security). Until then, the way described in the docs is perfectly fine. We're also going to talk about Messenger and how you can create endpoints that dispatch "messages" into Messenger (this is also something that API Platform has a bit about in their docs).

    Cheers!

  • 2019-06-17 Gabriel Mustiere

    Hey weaverryan, API Platform is really good for making projects quickly, but I've never met (or it's very rare), APIs without the need to make custom endpoints (I think the official documentation is confusing on the subject), do you plan to cover the subject, I'm in chapter 20. Thanks for the great job you do.

  • 2019-06-12 Vladimir Light

    what about "API Platform: OAuth2 Server" tutorial ?

  • 2019-05-27 Diego Aguiar

    Hey ElGovanni

    Sorry but I don't fully get your question. What you mean by "3rd party developers with limits"?

    Cheers!

  • 2019-05-25 ElGovanni

    Can we use api platform to publish it for 3rd part developers with limits?

  • 2019-05-21 Diego Aguiar

    :)

  • 2019-05-21 Peter Sorensen

    No-Docker API Platform tutorial. Finally! #dockersucks

  • 2019-05-16 weaverryan

    Hey @Fabio!

    We're not planning on it for the first tutorial, but it is on our radar for a future tutorial - I'll give it an internal upvote ;).

    Cheers!

  • 2019-05-16 Fabio Restrepo

    Hi, does this course cover live updates with mercure protocol

  • 2019-05-15 weaverryan

    Bah, ok *tomorrow*, I promise - we hit a last-second snag. Sorry about that!

  • 2019-05-13 weaverryan

    Wednesday :)

  • 2019-05-07 cybernet2u

    any news ?

  • 2019-04-26 Victor Bocharsky

    Hey Romeo,

    Thank you for your feedback! We will cover CRUD in this course, and will slightly mention GraphQL, but, unfortunately, GraphQL won't be a part of basics. We're going to cover GraphQL in a separate course - this topic deserves a separate tutorial.

    Cheers!

  • 2019-04-25 Dmitry Volya

    Awesome!

  • 2019-04-25 Romeo Tong

    It's good.
    I'm going to add GraphQL into Api-Platform and also with Symfony Flex.
    Did you include CRUD by GraphQL in this course? please.

  • 2019-04-24 Victor Bocharsky

    Hey Amin,

    Yes, we're going to cover oneToMany relation in this course, but probably not much complex than that, just simple oneToMany - it will be just basics of API-Platform.

    Cheers!

  • 2019-04-23 Amin Behravesh

    In Symfony I used to create a complex form, specially for oneToMany relations, you know using collection type, allow_add and other fascinating options, so is there anyway to have it in api platform? does this course cover things like this ?

  • 2019-04-16 Diego Aguiar

    Hey Manoj Kumar

    This course is totally focused on API Platform, so it won't cover how to develop an API in a TDD way. If you are interested in TDD, we have some courses about it (PHPSpec, PHPUnit, Behat), https://symfonycasts.com/tr...

    Cheers!

  • 2019-04-16 God Tier God

    This is what I was looking for !!

  • 2019-04-16 Victor Bocharsky

    Hey Manoj,

    Thank you for your interest in this topic! See my answer for more context: https://symfonycasts.com/sc...

    Cheers!

  • 2019-04-16 Victor Bocharsky

    Hey Imad,

    Unfortunately no, not in this episode at least. Security is a big separate topic, we're definitely going to cover it, but in next episodes. In this one we're going to cover basics only. Thank you for understanding!

    Cheers!

  • 2019-04-16 Manoj Kumar

    Will it cover TDD for APIs?

  • 2019-04-16 Manoj Kumar

    It would be nice to have it

  • 2019-04-15 Rafael

    Nice!

  • 2019-04-15 Diego Aguiar

    hahaha, we all have to wait ;)

  • 2019-04-15 Imad Zairig

    Cool,
    does this course cover API security with API-Platform ? :)

  • 2019-04-15 ElGovanni

    Finally

  • 2019-04-15 Manoj Kumar

    Waiting for it.......:D https://media2.giphy.com/me...