api-platform / docs Goto Github PK

I am running exact example from https://github.com/api-platform/docs/blob/2.1/admin/handling-relations-to-collections.md and I get an error:

Are docs not up to date or am I doing something wrong?

For example https://github.com/api-platform/docs/blob/2.1/admin/getting-started.md#using-custom-components was not working as well but I found solution at api-platform/admin#70

How about handling relations?

see api-platform/core#1464

In the getting started "Creating your First API with API Platform, in 5 Minutes" there is a typo in the example using POST on the REVIEW resource :

There is a comma at the end of the last row who thrown an error.

This code

{
    "book": "/books/1",
    "rating": 5,
    "body": "Interesting book!",
    "author": "Kévin",
    "publicationDate": "September 21, 2016",
}

should be

{
    "book": "/books/1",
    "rating": 5,
    "body": "Interesting book!",
    "author": "Kévin",
    "publicationDate": "September 21, 2016"
}

I looked around in the official documentation, on StackOverflow and so on, I didn't find any help on how to upgrade from 2.0.x to 2.1.x.
It would be nice to get some directions on how to perform such upgrade.

Hi,

I would like to documented my API with some descriptions and parameters on entities. I read the swagger specification, but it's not same on ApiResource annotation. Do you have an example ?

I don't find this in your documentation.

My annotation on Communication entity:

/**
 * @ApiResource(
 *     collectionOperations={
 *          "get"={
 *              "method"="GET",
 *              "parameters"={
 *                  "institution"={
 *                      "type"="string",
 *                      "required"=true
 *                  },
 *                  "language"={
 *                      "type"="string",
 *                      "required"=true
 *                  }
 *              },
 *              "description"="Communication collection"
 *          }
 *     },
 *     itemOperations={},
 *
 * )
 */

Thank's

Bertrand

A documentation about upload files system is existing or is planned ?
Like describe in api-platform/api-platform#12

Hi.

I have external oAuth Server build with FOSUserBundle and FOSOAuthServerBundle.
From frontend app I make a request to oAuth server and I get nice response with access_token.

On service with api-platform I tried to use HWIOAuthBundle, and it works, if I use grant_type code with oAuth login form and redirect, but when I get access_token by grant_type password, and send request to api with header Bearer i get response that I'm not loged in (access token is valid).

Any idea how to send request to api with token taken externally (not through HWIOAuth) ?

Hi folks,

i am totally new in api-platform (working with sf for few years now), have been trying to figure out how to call FOSUB to life, but the result is that i am writing this issue.

After reading first two chapters ('Creating a Fully Featured API in 5 Minutes' + 'Testing and Specifying the API') i moved to the main part of docs, and started with configuration.

As config says, i am enabling fos_user integration, then i am moving to a chapter FOSUser Bundle Integration.

'Here’s an example of declaration of a Doctrine ORM User class' - that's great, i will use that for the start - 'You need to use serialization groups to hide some properties...' - yeah, totally understood - 'First register the following service:' - wait, what? which service, the block of code below? That's the user model class, not a service. Then i figured out, that you've meant the next chapter...

API Platform allows to easily add a JWT-based authentication to your API using LexikJWTAuthenticationBundle.

API Platform is fully working with LexikJWTAuthenticationBundle.

In order to install the bundle please follow their documentation.

Hm, no. So which service should i enable? Totally lost here.

Let's stay here. I've created model for my user. It is of course extension for FOS\UserModel\Model\User - but... 'Fatal Error: Class 'FOS\UserBundle\Model\User' not found'

So what have you meant writing this? 'API Platform Core is shipped with a bridge for FOSUserBundle. If the FOSUser bundle is enabled, this bridge will use its UserManager to create, update and delete user resources.'.

Yes, it is enabled, but which bridge? Should i just install it on my own, or what? If you are saying that it is shipped with core, but you are calling the not existing paths, hm, so where is the point.

Hi, here is the resource used in core/Security.md :

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * Secured resource.
 *
 * @ApiResource(
 *     attributes={"access_control"="is_granted('ROLE_USER')"},
 *     collectionOperations={
 *         "get"={"method"="GET"},
 *         "post"={"method"="POST", "access_control"="is_granted('ROLE_ADMIN')"}
 *     },
 *     itemOperations={
 *         "get"={"method"="GET", "access_control"="is_granted('ROLE_USER') and object.owner == user"}
 *     }
 * )
 * @ORM\Entity
 */
class Book
{
    /**
     * @var int
     *
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    public $id;
    
    /**
     * @var string The title
     *
     * @ORM\Column
     * @Assert\NotBlank
     */
    public $title;
    
    /**
     * @ORM\Column
     */
    public $owner;
}

So I think that there is an error

This example is going to allow only fetching the book related to the current user. if he tries to fetch a book which is linked to his account, that will not return the resource. In addition, only admins are able to create books which means that a user could not create a book.

and it must be:

This example is going to allow only fetching the book related to the current user. if he tries to fetch a book which is not linked to his account, that will not return the resource.

links to tutorial does not work in index.md

Points to: /getting-started/xxxx
Should point to: /tutorial/xxxx

Can you please provide examples for this scenario, because documentation https://api-platform.com/docs/core/validation#using-validation-groups is not so obvious.

@dunglas @kbsali

Someone shared us is code to search with Elastic, maybe that could be useful ?

api-platform/api-platform#157 (comment)

Update the documentation to match the implementation
(current behavior described in the documentation displays a "deprecation" trace)

api-platform/core#938

It should be changed to an intuitive form, e.g. symfony/symfony-docs

So perhaps api-platform/docs

Hi there.

This is just a question, not a bug report.

Can you tell me where in the following example the admin_input group is added only for Books, or isnt this the case?

For my understanding with the code from this example the group admin_input is added on each ApiResource when conditions match.

https://github.com/dunglas/doc/blob/new_getting_started/core/serialization-groups-and-relations.md#changing-the-serialization-context-dynamically

Thanks for your help.

Cheers Ben

?exists[property]=<true|false|1|0>

Should be :

?property[exists]=<true|false|1|0>

Hi.
I try to create custom Delete action - before removing a item I want to remove connected items.

I have two entities: DrugUnified, which contains Drugs.
DrugUnified, can't be removed when Drugs are attached.

I have defined new action:

<?php

namespace AppBundle\Action\DrugUnified;

use AppBundle\Entity\DrugUnified;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
use Doctrine\Common\Persistence\ManagerRegistry;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class DrugUnifiedDelete
{

    private $doctrine,$em;


    public function __construct(ManagerRegistry $doctrine){
        $this->doctrine = $doctrine;
        $this->em = $this->doctrine->getManager();
    }

    /**
     * Add drugs to unified group
     *
     * @Route(
     *     name="api_drugunifieds_delete",
     *     path="/drug_unifieds/{id}",
     *     defaults={
     *                  "_api_resource_class"=DrugUnified::class,
     *                  "_api_item_operation_name"="drug_unified_delete"
     *      }
     * )
     * @Method("DELETE")
     */
    public function __invoke(Request $request, $data)
    {


        $drugUnifiedDefault = $this->em->getRepository('AppBundle:DrugUnified')->findOneBy(['originalSymbol'=>'0000000']);

        if(isset($data) && $data->getId() ){
            $drugRepo = $this->doctrine->getRepository('AppBundle:Drug');

            $drugs = $data->getDrugs();


            foreach ($drugs as $drug){
                    $data->removeDrug($drug);

                    $drug->setDrugunified($drugUnifiedDefault);
                    $this->em->persist($drug);
                    $this->em->flush();
            }
        }
        return $data;
    }

}

and attached it by annotation to Entity:

   @ApiResource(
                attributes={
                    "filters"={"apiOrder", "searchFilter", "searchOrFilter"},
                    "pagination_items_per_page"=50,
                    "force_eager"=true,
                    "normalization_context"={"groups"={"drugs_unified"}},
                },
                itemOperations={
                    "get"={"method"="GET"},
                    "put"={"method"="PUT"},
                    "deleteDrugUnified"={
                        "route_name"="api_drugunifieds_delete",
                        "swagger_context" = {
                            "parameters" = {
                                {
                                    "name" = "id",
                                    "in" = "path",
                                    "required" = "true",
                                    "type" = "string"
                                }
                            },
                            "summary" = "Remove drugs_unified, and assosiated drugs move to 'not assigned' group "
                        }
                    },
                    "add"={
                              "route_name"="api_drugunifieds_add_drug",
                              "swagger_context" = {
                                    "parameters" = {
                                        {
                                           "name" = "id",
                                           "in" = "path",
                                           "required" = "true",
                                           "type" = "string"
                                        },
                                        {
                                            "name" = "ids",
                                            "in" = "body",
                                            "type" = "string",
                                            "schema": {
                                                "type": "object",
                                                "properties": {
                                                    "ids": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "style": "simple"
                                        }
                                    },
                                    "summary" = "Add drugs to drugs_unified"
                              }
                   },
                    "remove"={
                        "route_name"="api_drugunifieds_remove_drug",
                        "swagger_context" = {
                            "parameters" = {
                                {
                                    "name" = "id",
                                    "in" = "path",
                                    "required" = "true",
                                    "type" = "string"
                                },
                                {
                                    "name" = "ids",
                                    "in" = "body",
                                    "type" = "string",
                                    "schema": {
                                        "type": "object",
                                        "properties": {
                                            "ids": {
                                            "   type": "string"
                                            }
                                        }
                                    },
                                    "style": "simple"
                                }
                            },
                            "summary" = "Add drugs to drugs_unified"
                        }
                    }
                }
    )

In swagger I see it, but when I make request, the build in action goes.

Here is my routing (custom routing are before build in):

  api_assortment_add_drugunified      PUT      ANY      ANY    /api/assortments/{id}/drug_unifieds/add     
  api_assortment_remove_drugunified   PUT      ANY      ANY    /api/assortments/{id}/drug_unifieds/delete  
  api_drugunifieds_add_drug           PUT      ANY      ANY    /api/drug_unifieds/{id}/drugs/add           
  api_drugunifieds_delete             DELETE   ANY      ANY    /api/drug_unifieds/{id}                     
  api_drugunifieds_remove_drug        PUT      ANY      ANY    /api/drug_unifieds/{id}/drugs/delete        
  api_entrypoint                      ANY      ANY      ANY    /api/{index}.{_format}                      
  api_doc                             ANY      ANY      ANY    /api/docs.{_format}                         
  api_jsonld_context                  ANY      ANY      ANY    /api/contexts/{shortName}.{_format}         
  api_doctors_get_collection          GET      ANY      ANY    /api/doctors.{_format}                      
  api_doctors_post_collection         POST     ANY      ANY    /api/doctors.{_format}                      
  api_doctors_get_item                GET      ANY      ANY    /api/doctors/{id}.{_format}                 
  api_doctors_put_item                PUT      ANY      ANY    /api/doctors/{id}.{_format}                 
  api_doctors_delete_item             DELETE   ANY      ANY    /api/doctors/{id}.{_format}                 
  api_drugs_get_collection            GET      ANY      ANY    /api/drugs.{_format}                        
  api_drugs_post_collection           POST     ANY      ANY    /api/drugs.{_format}                        
  api_drugs_get_item                  GET      ANY      ANY    /api/drugs/{id}.{_format}                   
  api_drugs_put_item                  PUT      ANY      ANY    /api/drugs/{id}.{_format}                   
  api_drugs_delete_item               DELETE   ANY      ANY    /api/drugs/{id}.{_format}                   
  api_assortments_get_collection      GET      ANY      ANY    /api/assortments.{_format}                  
  api_assortments_post_collection     POST     ANY      ANY    /api/assortments.{_format}                  
  api_assortments_get_item            GET      ANY      ANY    /api/assortments/{id}.{_format}             
  api_assortments_put_item            PUT      ANY      ANY    /api/assortments/{id}.{_format}             
  api_assortments_delete_item         DELETE   ANY      ANY    /api/assortments/{id}.{_format}             
  api_drugstores_get_collection       GET      ANY      ANY    /api/drugstores.{_format}                   
  api_drugstores_post_collection      POST     ANY      ANY    /api/drugstores.{_format}                   
  api_drugstores_get_item             GET      ANY      ANY    /api/drugstores/{id}.{_format}              
  api_drugstores_put_item             PUT      ANY      ANY    /api/drugstores/{id}.{_format}              
  api_drugstores_delete_item          DELETE   ANY      ANY    /api/drugstores/{id}.{_format}              
  api_employees_get_collection        GET      ANY      ANY    /api/employees.{_format}                    
  api_employees_post_collection       POST     ANY      ANY    /api/employees.{_format}                    
  api_employees_get_item              GET      ANY      ANY    /api/employees/{id}.{_format}               
  api_employees_put_item              PUT      ANY      ANY    /api/employees/{id}.{_format}               
  api_employees_delete_item           DELETE   ANY      ANY    /api/employees/{id}.{_format}               
  api_drug_sales_get_collection       GET      ANY      ANY    /api/drug_sales.{_format}                   
  api_drug_sales_post_collection      POST     ANY      ANY    /api/drug_sales.{_format}                   
  api_drug_sales_get_item             GET      ANY      ANY    /api/drug_sales/{id}.{_format}              
  api_drug_sales_put_item             PUT      ANY      ANY    /api/drug_sales/{id}.{_format}              
  api_drug_sales_delete_item          DELETE   ANY      ANY    /api/drug_sales/{id}.{_format}              
  api_drug_unifieds_get_collection    GET      ANY      ANY    /api/drug_unifieds.{_format}                
  api_drug_unifieds_post_collection   POST     ANY      ANY    /api/drug_unifieds.{_format}                
  api_drug_unifieds_get_item          GET      ANY      ANY    /api/drug_unifieds/{id}.{_format}           
  api_drug_unifieds_put_item          PUT      ANY      ANY    /api/drug_unifieds/{id}.{_format}     `

Also I wanted to make additional action for method 'Delete', but it always call default action instead, so I needed to create PUT actions: api_drugunifieds_remove_drug PUT ANY ANY /api/drug_unifieds/{id}/drugs/delete

Any idea, why always build in delete action is called for all Delete method actions?

On page docs/core/index.md the link to the Fixtures directory is broken. I think the directory has been removed from the target repository.

Not sure where this should now point to, but happy to submit a PR if someone can advise?

Could the repository be renamed to api-platform-docs, like symfony does it?

It's better when forking, doc is too common.

I noticed that when an Action Domain Responders documented here returns an entity object for storage the WriteListener will either perform a persist or remove operation based on the request's HTTP verb. This makes it difficult to perform update-or-insert operations without custom code.

I wonder if it'd be possible to add support to merge entities using a new _api_x attribute in the annotations/request, e.g. _api_cascade={merge|persist} comes to mind. For the time being this is the approach I'm going to be taking in my personal project.

If you think this isn't completely wrong and actually worth considering, I'd be happy to open a PR to api-platform too.

I am tryin to output a complex response as CSV like the documentation says. I just figured out that at least the following is missing in the docs, but I am not sure if I am 100% correct about the content types. So would be nice if someone could confirm this. I will create pull request then.

    formats:
        csv:      ['text/csv']
        yaml:     ['text/yaml']

Also, should I add my custom normalizer when its done? Out of the box its not possible to just enable the csv format:

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred",
  "detail": "To use the CSV encoder, each line in the data array must have the same structure. You may want to use a custom normalizer class to normalize the data format before passing it to the CSV encoder."
}

Todo:

• Figure out the best way to fix this issue (here is an example: api-platform/core#316)
• Update the documentation (seems someone tried this before: #21)

Hello,

I have a entity Invoice with a primary key "id"
If I browse the docs.jsonld#Invoice, I dont find any reference to this property. So on my client, my hydra parser based on API doc cannot understand how to hydrate this property and set it to null.

Do I need to configure something for api-platform to expose this primary key in the jsonld doc of an entity ?

Ref api-platform/core#1123
ping @meyerbaptiste

Hello,
there are some rendering errors in docs but I can't check my fixes will work if I can't reproduce the rendering :(

Do you use mkdocs for instance?

Mickaël

Currently I've added FOSOAuthServerBundle to my application to get OAuth2 support. This is working, but now I can not use the "Try out!"-Button in SwaggerUI, because I am not authenticated.

It would be nice to have an example for OAuth2 with Swagger Login support.
If someone tells me the solution, I am willing to write the tutorial.

The page https://api-platform.com/docs/core/operations references:

<!-- src/AppBundle/Resources/config/api_resources/resources.xml -->

<?xml version="1.0" encoding="UTF-8" ?>
<resources xmlns="https://api-platform.com/schema/metadata"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://api-platform.com/schema/metadata
           https://api-platform.com/schema/metadata/metadata-2.0.xsd">
    ...
</resources>

However, all of these URIs return a 404 error. Is it normal?

Greetings api-platform Team!

I would like to help translating the documentation of api-platform into spanish language. In order to do so, I have a couple of questions.

Should I make a new branch called Spanish and do the translation from there? an i18n/es-ES folder? or how would it be more convenient to have this translation?

Thanks in advance for your answer.

In GitHub documentation (core/getting-started.md), on branch master, routing is defined as following:

api:
    resource: '.'
    type:     'api'
    prefix:   '/api' # Optional

But, when I try, I get this error :

FileLoaderLoadException in Loader.php line 73:
Cannot load resource ".".

I fixed it by replacing :

api:
    resource: '.'
    type:     'api_platform'
    prefix:   '/api' # Optional

Hello everyone, I have the same issue as related on #298.

In the documentation, this is not really precise on this point, especially during denormalization.
https://api-platform.com/docs/core/serialization#changing-the-serialization-context-dynamically

public function createFromRequest(Request $request, bool $normalization, array $extractedAttributes = null) : array
{
    $context = $this->decorated->createFromRequest($request, $normalization, $extractedAttributes);
    $subject = $request->attributes->get('data');

    if ($subject instanceof Book && isset($context['groups']) && $this->authorizationChecker->isGranted('ROLE_ADMIN') && false === $normalization) {
        $context['groups'][] = 'admin_input';
    }

    return $context;
}

Here, $subject is null in denormalization, is this a normal behaviour ?

Thank you in advance, I love this project ❤️

The initial section on how to modify the parsed API doc shown below appears to be invalid…

const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
  .then(api => {
    api.resources.map(resource => {
      const books = api.resources.find(r => 'books' === r.name);
      books.fields.find(f => 'description' === f.name).fieldComponent = <RichTextField source="description" key="description"/>;
      books.fields.find(f => 'description' === f.name).inputComponent = <RichTextInput source="description" key="description"/>;

      return resource;
    });

    return api;
  })
;

This appears to loop through the array (using map), but then attempts to find the books (using find). Should this be one or other?

Also, in my setup it seams that the api variable has a child called api which contains resources rather than resources being a direct child of the api argument passed in.

Happy to submit a PR if this is correct?…

const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
  .then(api => {
    const books = api.api.resources.find(r => 'books' === r.name);
    books.fields.find(f => 'description' === f.name).fieldComponent = <RichTextField source="description" key="description"/>;
    books.fields.find(f => 'description' === f.name).inputComponent = <RichTextInput source="description" key="description"/>;

    return api;
  })
;

Also, when I use the parseHydraDocumentation() I receive the following error. Any idea why?…

index.js:2177 Warning: Failed prop type: Invalid prop `api` of type `Api` supplied to `_class`, expected instance of `Api`.
    in _class (created by HydraAdmin)
    in HydraAdmin (at Admin.js:33)
    in Admin (at App.js:5)
    in Unknown (at index.js:7)

… It looks like the API object it's returning doesn't match the expected API class object for some reason.

api-platform/core#938
api-platform/core#521

public function createFromRequest(Request $request, bool $normalization, array $extractedAttributes = null) : array
{
    $context = $this->decorated->createFromRequest($request, $normalization, $extractedAttributes);
    $subject = $request->attributes->get('data');

    if ($subject instanceof Book && isset($context['groups']) && $this->authorizationChecker->isGranted('ROLE_ADMIN') && false === $normalization) {
        $context['groups'][] = 'admin_input';
    }

    return $context;
}

I've tried to decorate context builder but the $subject is always null.

Menu has serialization-groups-and-relations but the documentation is available under serialization

Did we forgot to update the menu/index according to recent changes?

ref api-platform/api-platform#567

I'm currently attempting to filter my OneToMany collection results, without much luck.

I've tried setting up a filter as stated in the docs here to no avail.
With the following code, I only get an option to filter on the Foos collection /api/foos <- This request never actually finishes with the filter applied, even with pagination set to 1 per page.

Where I want/need it to be on /api/foos/1?bar.isRetired=false and to return a result of 1 'Bar' with many 'foos', but where 'foo.isRetired = false'

Example

// config/packages/api_filters.yaml
services:
    filters.retired_filter:
            parent: 'api_platform.doctrine.orm.boolean_filter'
            arguments: [ { bars.isRetired: ~ } ]
            tags: [ 'api_platform.filter' ]


// src/Entity/Foo.php

/* @ApiResource(attributes={"filters"={"filters.retired_filter"}}) */
class Foo
{
    private $id;
    private $name;
    /** @ORM\OneToMany(targetEntity="Bars", mappedBy="foo") */
    private $bars;
    public function __construct(){
        $this->bars = new ArrayCollection();
    }
}

// src/Entity/Bar.php

/* @ApiResource() */
class Bar
{
    private $id;
    private $name;
    /* @ORM\Column(name="is_retired", type="boolean") */
    private $isRetired;
    /* @ORM\ManyToOne(targetEntity="Foo", inversedBy="bars") */
    private $foo;
}

Any pointers would be highly appreciated.

I'm using Symfony4 with Flex and API-Platform 2.1, I've also asked this question on StackOverflow

Sorry I have a lot of questions these days, but I am really looking forward to upgrade a big project from api-platform v1 to v2 and I have a lot of custom logic.

To migrate easily, I need a way to acces the original data fetched from the persistence layer in my controller.

First I created a EventSubscriber cloning the $request->attributes->get('data'). It works fine for "simple" cases, like controller access before updating entity (like "you can only change ownership of an item if you own the item"), but sometimes I need more control between the entity and the request content.

I found the _api_receive argument to be a very good candidate in blocking the DeserializeListener to do it's job, but this feature is undocumented. (and it unfortunatly also skip the validation process).

Is it a "private" / internal feature or is just missing from the documentation ? (if so, I can make a PR of course)

• Should not be @Resource but @ApiResource
• Should not be @Property but @ApiProperty
  see #56
• Update the docs about serialization groups by @dunglas
• Update the FOSUserBundle docs by @dunglas
• Update the angularJS tutorial / add a to-go angular backend.
• maybe do something about react
• Update docs about nelmio & swagger.
• add to doc api-platform/core#521
• add range filters to the doc
• add doc about HAL

Do you see other things ?

By clicking with the middle button of our mouse, on an internal link, we expect that it respects the behavior of our browser (in my case, with Firefox, it should open the link into a new tab). But it doesn't. It opens the content into the same tab. It's very annoying (and not consistent with external links).

(and why having 1.65 MB of JS to just display few KB of html ? Static HTML content is enough for documentation IMHO...)

see api-platform/schema-generator#33

Docs says "The Symfony Serializer component allows to specify the definition of serialization using XML, YAML, or annotations. "

But there's no sample how to setup for example this:

/**
 * @ApiResource(
 *     attributes={"normalization_context"={"groups"={"get"}}},
 *     itemOperations={
 *          "get"={"method"="GET"},
 *          "put"={"method"="PUT", "normalization_context"={"groups"={"put"}}}
 *     }
 * )
 */

in XML or YAML. AFAIK there's also no XML Schema provided (as Symfony does) so it's ever harder to discover the functionality.

It would be great to provide a sample XML / YAML config, even just in a Git repo somewhere. I've looked in core's tests, there isn't one there either.

api-platform/core#1694

I want to remove the logo on the top right of the documentation.

Reading documentation I can find how to overwrite Swagger information, but I am trying to find some way to overwrite Swagger templates, and I don't know how to do it.

Is it possible to do it?

As it's said in the docs

API Platform Core will automatically detect the best resolving format depending on:

enabled formats (link to docs for this / see below)
the Accept HTTP header

besides the Accept header, it's possible to specify format in the url (e.g /api/users.json)

.json corresponds to "Accept: application/json"
.jsonld corresponds to "Accept: application/ld+json"
.html corresponds to "Accept: text/html"

/api/users

{
    "@context": "/api/contexts/User",
    "@id": "/api/users",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/api/users/1",
            "@type": "User",
            "email": "[email protected]",
            "id": 1,
            "mobilePhone": null,
            "roles": ["ROLE_USER"],
            "username": "foo"
        }
    ],
    "hydra:search": {},
    "hydra:totalItems": 2
}

/api/users.json

[
    {
        "email": "[email protected]",
        "id": 1,
        "mobilePhone": null,
        "roles": ["ROLE_USER"],
        "username": "foo"
    }
]

Should we add something like this to the docs or you think it's not necessary?

Hi,
I use this documentation to have swagger doc on custom routes : #143 (comment)

In >>> ... <<< below I want to use $ref (https://swagger.io/specification/#reference-object-93) or something else to reference an existing object :

 "responses" = {
       "201" = {
            "description" = "email with reset token has been sent",
              "schema" =  {
                  "type" = "object",
                  "required" = {
                       "email",
                       "username"
                  },
                 "properties" = {
                     "email" = {
          >>>>>>>>>>>>>>  type" = "string" <<<<<<<<<<<<<<<<<<<<<<<<
                     },

Is there a way to reference Custom Object in type like type = "MyCustomObject" ?

Hi. I use YAML configuration format on the project.
@dunglas , could you add example for using a static method of same entity in YAML in this doc https://api-platform.com/docs/core/validation/#dynamic-validation-groups ?

resources:
   AppBundle\Entity\Book:
       ...
       attributes:
           validation_groups: Book::validationGroups

It looks like the example in errors handling section is taking the wrong method argument.

<?php

namespace AppBundle\EventSubscriber;

use ApiPlatform\Core\EventListener\EventPriorities;
use AppBundle\Entity\Product;
use AppBundle\Exception\ProductNotFoundException;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
use Symfony\Component\HttpKernel\KernelEvents;

final class ProductManager implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::REQUEST => ['checkProductAvailability', EventPriorities::POST_DESERIALIZE],
        ];
    }

    public function checkProductAvailability(GetResponseForControllerResultEvent $event): void
    {
        $product = $event->getControllerResult();
        if (!$product instanceof Product || !$event->getRequest()->isMethodSafe(false)) {
            return;
        }

        if (!$product->isPubliclyAvailable()) {
            // Using internal codes for a better understanding of what's going on
            throw new ProductNotFoundException(sprintf('The product "%s" does not exist.', $product->getId()));
        }
    }
}

In the example the function uses GetResponseForControllerResultEvent type hint, but this is only available during kernel.view

So, running the example code will throw an error

Type error: Argument 1 passed to ... must be an instance of Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent, instance of Symfony\Component\HttpKernel\Event\GetResponseEvent given

For example, api-bundle/the-event-system.md still talks about the no longer existent custom events...

I remember @dunglas updating some docs last time to mention that they're outdated, but those notices seem to be gone now. Is this a glitch when extracting the docs from DunglasApiBundle, or is it intended?

Hello,

I'm following the instructions from the doc
https://api-platform.com/doc/1.0/getting-started/api
Creating your first API with API Platform

but I got the an error "[critical] Type "SocialMediaPosting" cannot be found." when executing the generator.

Is there something missing in the doc please ?

I tried with and without the config
rdfa:
- https://raw.githubusercontent.com/schemaorg/schemaorg/sdo-gozer/data/schema.rdfa
in app/config/schema.yml, but there is almost the same error.

Below both output:

• without the config
  $ bin/schema generate-types src/ app/config/schema.yml -vvv
  [critical] Type "SocialMediaPosting" cannot be found.
  [critical] Type "BlogPosting" cannot be found.
  [critical] Type "Article" cannot be found.
  [critical] Type "CreativeWork" cannot be found.
  [critical] Type "Thing" cannot be found.
  [critical] Type "Person" cannot be found.
• with the config
  $ bin/schema generate-types src/ app/config/schema.yml -vvv
  [critical] Type "SocialMediaPosting" cannot be found.

Plateform: Windows 10 Home
PHP: PHP 5.5.38 (cli) (built: Jul 20 2016 11:16:06) (x86)

Extract from composer.lock
"name": "api-platform/schema-generator",
"version": "v1.0.0",

Thanks in advance.

Best regards,
Christophe