RestFul API - fix and upgrade description

[wbloszyk]

Current RestFul API is autdated and should be updated. 'REST' routing type is deprecated, friendsofsymfony/rest-bundle and nelmio/api-doc-bundle should be upgrade to allow use Symfony5. Will be nice to add functional tests too, to keep it working in feature.

Work description

fix router unavailable resource

In this scope some controller services will be added to allow import routing from REST type. It is quick fix for current REST API.

drop 'REST' routing type in favor for xml

REST routing type is deprecated. Before another change it must be replace by other type. In Sonata we are using xml so this type should be used in API too.

support for friendsofsymfony/rest-bundle v3

Add support, some pedantic change in commets/docblock.

Update Swagger definition in order to be compatible with string identifiers

This RPs will allow use other type than current int. string will allow use other type too.

[BC-break] improve models for swagger

We can consider 2 cases.

• People who use API based directly on urls.
  Here BC will be keep.
• People who use OAS definitions.
  Here BC will not be keep. Anyway provide empty interfaces as OAS models is also unhelpful. Provide BC-break in this case (for fix bad code) is nessessery. OAS should return end entity with people jms dictionary for it. (example)

Conclusion:

OAS model for user should:

• change from Sonata\UserBundle\Model\UserInterface to App\Entity\SonataUserUser
• add src\Resources\config\serializer\Entity.SonataUserUser.xml (by recipies)

TODO:

• SonataClassificationBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• SonataMediaBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• SonataNewsBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• SonataNotificationBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• SonataPageBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• SonataUserBundle
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger
• ecomerce
  • fix router unavailable resource
  • drop 'REST' routing type in favor for xml
  • support for friendsofsymfony/rest-bundle v3
  • Update Swagger definition in order to be compatible with string identifiers
  • support for nelmio/api-doc-bundle v3
  • improve models for swagger

also TODO

• add deprecation, trigger_error and next_major notices

Sandbox for API tests

sonata-project/sandbox#629

This issue is create based on @phansys work in:

• https://github.com/sonata-project/SonataUserBundle/pull/1185/files
• Update conflict constraint for "nelmio/api-doc-bundle" in order to allow version 3 SonataUserBundle#1186

[jordisala1991]

I think this upgrade will allow to be closer to sf5 and it should be done.

But, what do you think if in the future we move to Api platform generated api? It seems to be more updated and we will have better support? wdyt?

This movement is being done in sylius too: Sylius/Sylius#11250

@sonata-project/contributors

[wbloszyk]

IMHO STEP 1 should be release as fast as possible. Other things can wait as long as Symfony5 is not support.

[wbloszyk]

List of route name for Sonata API

#	Route name	Path	Log
13	sonata_api_classification_category_get_categories	/api/classification/categories.{_format}	Path does not match
14	sonata_api_classification_category_get_category	/api/classification/categories/{id}.{_format}	Path does not match
15	sonata_api_classification_category_post_category	/api/classification/categories.{_format}	Path does not match
16	sonata_api_classification_category_put_category	/api/classification/categories/{id}.{_format}	Path does not match
17	sonata_api_classification_category_delete_category	/api/classification/categories/{id}.{_format}	Path does not match
18	sonata_api_classification_collection_get_collections	/api/classification/collections.{_format}	Path does not match
19	sonata_api_classification_collection_get_collection	/api/classification/collections/{id}.{_format}	Path does not match
20	sonata_api_classification_collection_post_collection	/api/classification/collections.{_format}	Path does not match
21	sonata_api_classification_collection_put_collection	/api/classification/collections/{id}.{_format}	Path does not match
22	sonata_api_classification_collection_delete_collection	/api/classification/collections/{id}.{_format}	Path does not match
23	sonata_api_classification_tag_get_tags	/api/classification/tags.{_format}	Path does not match
24	sonata_api_classification_tag_get_tag	/api/classification/tags/{id}.{_format}	Path does not match
25	sonata_api_classification_tag_post_tag	/api/classification/tags.{_format}	Path does not match
26	sonata_api_classification_tag_put_tag	/api/classification/tags/{id}.{_format}	Path does not match
27	sonata_api_classification_tag_delete_tag	/api/classification/tags/{id}.{_format}	Path does not match
28	sonata_api_classification_context_get_contexts	/api/classification/contexts.{_format}	Path does not match
29	sonata_api_classification_context_get_context	/api/classification/contexts/{id}.{_format}	Path does not match
30	sonata_api_classification_context_post_context	/api/classification/contexts.{_format}	Path does not match
31	sonata_api_classification_context_put_context	/api/classification/contexts/{id}.{_format}	Path does not match
32	sonata_api_classification_context_delete_context	/api/classification/contexts/{id}.{_format}	Path does not match
33	sonata_api_news_comment_get_comment	/api/news/comments/{id}.{_format}	Path does not match
34	sonata_api_news_comment_delete_comment	/api/news/comments/{id}.{_format}	Path does not match
35	sonata_api_news_post_get_posts	/api/news/posts.{_format}	Path does not match
36	sonata_api_news_post_get_post	/api/news/posts/{id}.{_format}	Path does not match
37	sonata_api_news_post_post_post	/api/news/posts.{_format}	Path does not match
38	sonata_api_news_post_put_post	/api/news/posts/{id}.{_format}	Path does not match
39	sonata_api_news_post_delete_post	/api/news/posts/{id}.{_format}	Path does not match
40	sonata_api_news_post_get_post_comments	/api/news/posts/{id}/comments.{_format}	Path does not match
41	sonata_api_news_post_post_post_comments	/api/news/posts/{id}/comments.{_format}	Path does not match
42	sonata_api_news_post_put_post_comments	/api/news/posts/{postId}/comments/{commentId}.{_format}	Path does not match
43	sonata_api_media_gallery_get_galleries	/api/media/galleries	Path does not match
44	sonata_api_media_gallery_get_gallery	/api/media/galleries/{id}	Path does not match
45	sonata_api_media_gallery_get_gallery_medias	/api/media/galleries/{id}/medias	Path does not match
46	sonata_api_media_gallery_get_gallery_galleryhasmedias	/api/media/galleries/{id}/galleryhasmedias	Path does not match
47	sonata_api_media_gallery_post_gallery	/api/media/galleries	Path does not match
48	sonata_api_media_gallery_put_gallery	/api/media/galleries/{id}	Path does not match
49	sonata_api_media_gallery_post_gallery_media_galleryhasmedia	/api/media/galleries/{galleryId}/media/{mediaId}/galleryhasmedia	Path does not match
50	sonata_api_media_gallery_put_gallery_media_galleryhasmedia	/api/media/galleries/{galleryId}/media/{mediaId}/galleryhasmedia	Path does not match
51	sonata_api_media_gallery_delete_gallery_media_galleryhasmedia	/api/media/galleries/{galleryId}/media/{mediaId}/galleryhasmedia	Path does not match
52	sonata_api_media_gallery_delete_gallery	/api/media/galleries/{id}	Path does not match
53	sonata_api_media_media_get_media	/api/media/media	Path does not match
54	sonata_api_media_media_get_medium	/api/media/media/{id}	Path does not match
55	sonata_api_media_media_get_medium_formats	/api/media/media/{id}/formats	Path does not match
56	sonata_api_media_media_get_medium_binary	/api/media/media/{id}/binaries/{format}	Path does not match
57	sonata_api_media_media_delete_medium	/api/media/media/{id}	Path does not match
58	sonata_api_media_media_put_medium	/api/media/media/{id}	Path does not match
59	sonata_api_media_media_post_provider_medium	/api/media/media/providers/{provider}/media	Path does not match
60	sonata_api_media_media_put_medium_binary_content	/api/media/media/{id}/binary/content	Path does not match
61	sonata_api_notification_message_get_messages	/api/notification/messages.{_format}	Path does not match
62	sonata_api_notification_message_post_message	/api/notification/messages.{_format}	Path does not match
63	sonata_api_ecommerce_product_get_products	/api/ecommerce/products.{_format}	Path does not match
64	sonata_api_ecommerce_product_get_product	/api/ecommerce/products/{id}.{_format}	Path does not match
65	sonata_api_ecommerce_product_post_product	/api/ecommerce/products/{provider}.{_format}	Path does not match
66	sonata_api_ecommerce_product_put_product	/api/ecommerce/products/{id}.{_format}	Path does not match
67	sonata_api_ecommerce_product_delete_product	/api/ecommerce/products/{id}.{_format}	Path does not match
68	sonata_api_ecommerce_product_get_product_productcategories	/api/ecommerce/products/{id}/productcategories.{_format}	Path does not match
69	sonata_api_ecommerce_product_get_product_categories	/api/ecommerce/products/{id}/categories.{_format}	Path does not match
70	sonata_api_ecommerce_product_get_product_productcollections	/api/ecommerce/products/{id}/productcollections.{_format}	Path does not match
71	sonata_api_ecommerce_product_get_product_collections	/api/ecommerce/products/{id}/collections.{_format}	Path does not match
72	sonata_api_ecommerce_product_get_product_deliveries	/api/ecommerce/products/{id}/deliveries.{_format}	Path does not match
73	sonata_api_ecommerce_product_get_product_packages	/api/ecommerce/products/{id}/packages.{_format}	Path does not match
74	sonata_api_ecommerce_product_get_product_variations	/api/ecommerce/products/{id}/variations.{_format}	Path does not match
75	sonata_api_ecommerce_order_get_orders	/api/ecommerce/orders.{_format}	Path does not match
76	sonata_api_ecommerce_order_get_order	/api/ecommerce/orders/{id}.{_format}	Path does not match
77	sonata_api_ecommerce_order_get_order_orderelements	/api/ecommerce/orders/{id}/orderelements.{_format}	Path does not match
78	sonata_api_ecommerce_invoice_get_invoices	/api/ecommerce/invoices.{_format}	Path does not match
79	sonata_api_ecommerce_invoice_get_invoice	/api/ecommerce/invoices/{id}.{_format}	Path does not match
80	sonata_api_ecommerce_invoice_get_invoice_invoiceelements	/api/ecommerce/invoices/{id}/invoiceelements.{_format}	Path does not match
81	sonata_api_ecommerce_address_get_addresses	/api/ecommerce/addresses.{_format}	Path does not match
82	sonata_api_ecommerce_address_get_address	/api/ecommerce/addresses/{id}.{_format}	Path does not match
83	sonata_api_ecommerce_address_post_address	/api/ecommerce/addresses.{_format}	Path does not match
84	sonata_api_ecommerce_address_put_address	/api/ecommerce/addresses/{id}.{_format}	Path does not match
85	sonata_api_ecommerce_address_delete_address	/api/ecommerce/addresses/{id}.{_format}	Path does not match
86	sonata_api_ecommerce_customer_get_customers	/api/ecommerce/customers.{_format}	Path does not match
87	sonata_api_ecommerce_customer_get_customer	/api/ecommerce/customers/{id}.{_format}	Path does not match
88	sonata_api_ecommerce_customer_post_customer	/api/ecommerce/customers.{_format}	Path does not match
89	sonata_api_ecommerce_customer_put_customer	/api/ecommerce/customers/{id}.{_format}	Path does not match
90	sonata_api_ecommerce_customer_delete_customer	/api/ecommerce/customers/{id}.{_format}	Path does not match
91	sonata_api_ecommerce_customer_get_customer_orders	/api/ecommerce/customers/{id}/orders.{_format}	Path does not match
92	sonata_api_ecommerce_customer_get_customer_addresses	/api/ecommerce/customers/{id}/addresses.{_format}	Path does not match
93	sonata_api_ecommerce_customer_post_customer_address	/api/ecommerce/customers/{id}/addresses.{_format}	Path does not match
94	sonata_api_ecommerce_basket_get_baskets	/api/ecommerce/baskets.{_format}	Path does not match
95	sonata_api_ecommerce_basket_get_basket	/api/ecommerce/baskets/{id}.{_format}	Path does not match
96	sonata_api_ecommerce_basket_get_basket_basketelements	/api/ecommerce/baskets/{id}/basketelements.{_format}	Path does not match
97	sonata_api_ecommerce_basket_post_basket	/api/ecommerce/baskets.{_format}	Path does not match
98	sonata_api_ecommerce_basket_put_basket	/api/ecommerce/baskets/{id}.{_format}	Path does not match
99	sonata_api_ecommerce_basket_delete_basket	/api/ecommerce/baskets/{id}.{_format}	Path does not match
100	sonata_api_ecommerce_basket_post_basket_basketelements	/api/ecommerce/baskets/{id}/basketelements.{_format}	Path does not match
101	sonata_api_ecommerce_basket_put_basket_basketelements	/api/ecommerce/baskets/{basketId}/basketelements/{elementId}.{_format}	Path does not match
102	sonata_api_ecommerce_basket_delete_basket_basketelements	/api/ecommerce/baskets/{basketId}/basketelements/{elementId}.{_format}	Path does not match
103	sonata_api_block_get_block	/api/page/blocks/{id}.{_format}	Path does not match
104	sonata_api_block_put_block	/api/page/blocks/{id}.{_format}	Path does not match
105	sonata_api_block_delete_block	/api/page/blocks/{id}.{_format}	Path does not match
106	sonata_api_page_get_pages	/api/page/pages.{_format}	Path does not match
107	sonata_api_page_get_page	/api/page/pages/{id}.{_format}	Path does not match
108	sonata_api_page_get_page_blocks	/api/page/pages/{id}/blocks.{_format}	Path does not match
109	sonata_api_page_get_page_pages	/api/page/pages/{id}/pages.{_format}	Path does not match
110	sonata_api_page_post_page_block	/api/page/pages/{id}/blocks.{_format}	Path does not match
111	sonata_api_page_post_page	/api/page/pages.{_format}	Path does not match
112	sonata_api_page_put_page	/api/page/pages/{id}.{_format}	Path does not match
113	sonata_api_page_delete_page	/api/page/pages/{id}.{_format}	Path does not match
114	sonata_api_page_post_page_snapshot	/api/page/pages/{id}/snapshots.{_format}	Path does not match
115	sonata_api_page_post_pages_snapshots	/api/page/pages/snapshots.{_format}	Path does not match
116	sonata_api_site_get_sites	/api/page/sites.{_format}	Path does not match
117	sonata_api_site_get_site	/api/page/sites/{id}.{_format}	Path does not match
118	sonata_api_site_post_site	/api/page/sites.{_format}	Path does not match
119	sonata_api_site_put_site	/api/page/sites/{id}.{_format}	Path does not match
120	sonata_api_site_delete_site	/api/page/sites/{id}.{_format}	Path does not match
121	sonata_api_snapshot_get_snapshots	/api/page/snapshots.{_format}	Path does not match
122	sonata_api_snapshot_get_snapshot	/api/page/snapshots/{id}.{_format}	Path does not match
123	sonata_api_snapshot_delete_snapshot	/api/page/snapshots/{id}.{_format}	Path does not match
124	sonata_api_user_user_get_users	/api/user/users.{_format}	Path does not match
125	sonata_api_user_user_get_user	/api/user/users/{id}.{_format}	Path does not match
126	sonata_api_user_user_post_user	/api/user/users.{_format}	Path does not match
127	sonata_api_user_user_put_user	/api/user/users/{id}.{_format}	Path does not match
128	sonata_api_user_user_delete_user	/api/user/users/{id}.{_format}	Path does not match
129	sonata_api_user_user_post_user_group	/api/user/users/{userId}/groups/{groupId}.{_format}	Path does not match
130	sonata_api_user_user_delete_user_group	/api/user/users/{userId}/groups/{groupId}.{_format}	Path does not match
131	sonata_api_user_group_get_groups	/api/user/groups.{_format}	Path does not match
132	sonata_api_user_group_get_group	/api/user/groups/{id}.{_format}	Path does not match
133	sonata_api_user_group_post_group	/api/user/groups.{_format}	Path does not match
134	sonata_api_user_group_put_group	/api/user/groups/{id}.{_format}	Path does not match
135	sonata_api_user_group_delete_group	/api/user/groups/{id}.{_format}	Path does not match
136	nelmio_api_doc_index	/api/doc/{view}	Route matches!

[wbloszyk]

Still huge work to do but it is start working 😄

[wbloszyk]

STEP 2 is ready but need be merge in some order, otherwise travis will not install rest-bundle v3:

• release NotificationBundle
• merge MediaBundle
• release MediaBundle
• merge ClassificationBundle
• release ClassificationBundle

then NewsBundle and ecommerce can be merge.

@greg0ire Can you help with releases?

[wbloszyk]

I update this issue. I think we have pattern to resolve this issue (based on my tests and your nelmio support).

IMHO we should spit it to 3 PR for each bundle:

1. start from functional test(with smoke test) - example in ClassificationBundle
2. drop 'REST' routing type in favor for xml and add support for rest-bundle v3 (in one PR)
3. add support for nelmio/api-doc-bundle v3

@phansys Can you finish UserBundle? I will working on it in Thursday.

[phansys]

@phansys Can you finish UserBundle? I will working on it in Thursday.

I think after the merge of sonata-project/SonataUserBundle#1198, I can rebase sonata-project/SonataUserBundle#1186.
Please, let me know if that seems fine for you.

[VincentLanglet]

What's the status of this ?

[jordisala1991]

The api is getting deprecated. I think we can close this.