Core: Roadmap to version 2

[dunglas]

• [x] Finish #375
• [x] Rename the namespace Dunglas\ApiBundle to ApiPlatform\Core (or something better?)
• [x] Move Symfony specific classes and config to the Bridge\Symfony namespace (including the bundle)
• [x] Move the Composer dependency to symfony/framework-bundle in the require-dev and suggest section
• [ ] Update the doc

[lsmith77]

I agree with your design decision to leave FOSRestBundle out of the the required dependencies but I would recommend to look into integrating it optionally for content negotiation and body decoding etc.

[dunglas]

Hi @lsmith77 the v2 already integrates willdurand/Negotiation (as FOSRest AFAIK) for content negotiation: https://github.com/api-platform/doc/blob/master/api-bundle/content-negotiation.md

The body decoding is currently handled by the Symfony serializer: https://github.com/dunglas/DunglasApiBundle/blob/master/Action/PostCollectionAction.php#L50-L54

This library doesn't use the Symfony form framework (it uses directly the serializer to hydrate entities). Does FOSRest have an interest in such case?

I fully agree with you that we should find ways to make both projects sharing some code and it's why we choose willdurand/Negotiation for that. Do you know some other parts that can be shared?

[sroze]

One very convenient feature of FOSRestBundle is the @View view listener. We should introduce such a feature for custom operations but that's already in mind :)

Else, like @dunglas I'm happy to see what else and how we can share between the both!

[lsmith77]

configuring the priorities is also a key aspect of content negotiation which FOSRestBundle supports.
for body decoding we are not using the serializer due to security concerns.

@sroze FYI the @View annotation is based on SensioFrameworkExtraBundle

[dunglas]

We also support priorities configuration:

• if the requested Content-Type is available it is used (according to requested priorities)
• else the first element in the list of supported formats is used

Do you have more information about these security concerns? Is API Platform vulnerable?

[lsmith77]

In the rest bundle you can also configure the server side priorities to some degree.

The security concerns are mostly related to potentially risking users to be able to make instances of classes you do not want before the security layer can kick in our the controller can determine which classes to support. Or if it's delayed sufficiently, then all earlier listeners relying on request data will not work.

[sroze]

@lsmith77 not sure to see any use case where this server-side priorities that can't be solved by the format order. If you've some, happy to find a solution :)

[lsmith77]

BTW .. FOSRestBundle 2.0 is fairly far in the development but if there is anything do to in order to align things then let me know.

@dunglas BTW for content type negotiation you should use the Accept header

[dunglas]

We use the Accept header.

[lsmith77]

ah ok .. as for priorities .. imho it makes sense for api platform to support content negotiation for its preferred mime types .. but anything more complex I would delegate to FOSRestBundle.

[fbourigault]

Rename the namespace DunglasApiBundle to ApiPlatform\Core (or something better?)

Have you plans for splitting what you want to name Core into more bundles/libraries ? IMHO, naming something _core_ is an architecture smell but it can take lots of time to avoid.

[dunglas]

@fbourigault yes core will be the central repository (like symfony/symfony) and will be split in some bundle/components (like Symfony components and bundles).

[fbourigault]

:+1:

[sstok]

About the security part, I actually have a use-case where I need to do more checking then the security system alone (package limitations). I recently found this https://github.com/radarphp/Radar.Project/blob/1.x/docs/domain.md Which keeps most of the Domain EntryPoint logic in the ApplicationServices, so you can easily support more complex cases with ease.

[jonny827]

Is there a proposed timeline of production use for version 2 of the DunglasApiBundle and/or ApiPlatform? Just want to know if I should spend the time to build with the current release or if version 2 will be down the pipeline in the coming weeks?

[dunglas]

The development of the version 2 is finished at 80% but - as it requires some components of Symfony 3.1 - the production version will be released some time after SF 3.1 (in May).

I strongly encourage you to use the 1.x branch for now (the 1.1 version will be released as soon as all Behat extensions we use are compatible with Symfony 3).

[3kynox]

I will need content negociation to export api in other formats before may :)

Also, we will not use SF3 untill it pass to LTS (3.4). So hope api-platform 2.0 will work as well with SF2.8.

[mvrhov]

@3kynox It was said one comment above yours. That for 2.0 at least symfony 3.1 will be required because it will be the only version with required features.

[3kynox]

I can read, thanks, I saw previous post. That said, @dunglas tells in some disussions there's no problems at all to use api-platform both in SF2.x or 3.x.

We use actually api-platform in production environment, and we MUST be in 2.8LTS untill next LTS release. Also I'll need new api export features only available on api-platform 2.0 (using content-negociation).

Then, just thoughts here... and just hope api-platform 2.0 will be available also in SF2.8.

[dunglas]

The v2 is now usable (but for dev only, not in prod): #375

The plan is:

• Finish things in this todo list (starting to make phpunit tests green)
• Release a "developper preview" version relying on Symfony 3.1@dev
• Release a stable version at the same time than Symfony 3.1 (in May)

[dunglas]

The v2 requires some components of Symfony 3.1 (but not all). Especially the serializer. It also requires PHP 7.

[3kynox]

Thanks for answer @dunglas.

We use actually PHP7 but we did not planned to update Symfony to 3.1.
No ways keeping SF2.8 and use API-Platform v2 ?

[mvrhov]

Any particular reason to require PHP 7?

[sroze]

@mvrhov we can use return types? :)

[dunglas]

@3kynox not for the serializer. For other components it should be fine. (You can still install symfony/symfony in 2.8 and symfony/serializer in 3.1).

@mvrhov because of scalar types hints, return types, ??...

[mvrhov]

Just asking.
I hate repackaging ubuntu's php packages so they suit our needs because this usually takes a significant time for every mayor php release.

[soyuka]

Use docker it gets easier :)

[dunglas]

As you can see, most of the work is now done. Last but not least: updating the doc.

[soyuka]

That's all I'm waiting for to try it :)

[sroze]

Please don't, try it and help us to update/improve the documentation :)
On Fri, 19 Feb 2016 at 07:46, Antoine Bluchet [email protected]
wrote:

That's all I'm waiting for to try it :)

—
Reply to this email directly or view it on GitHub
https://github.com/dunglas/DunglasApiBundle/issues/376#issuecomment-186105675
.

[soyuka]

Yes I'm on it anyway but this implies php7 and symfony 3. Just wanted to
know major configuration changes, the rest I can handle :).
Le ven. 19 févr. 2016 à 08:47, Samuel ROZE [email protected] a
écrit :

Please don't, try it and help us to update/improve the documentation :)
On Fri, 19 Feb 2016 at 07:46, Antoine Bluchet [email protected]
wrote:

That's all I'm waiting for to try it :)

—
Reply to this email directly or view it on GitHub
<
https://github.com/dunglas/DunglasApiBundle/issues/376#issuecomment-186105675

.

—
Reply to this email directly or view it on GitHub
https://github.com/dunglas/DunglasApiBundle/issues/376#issuecomment-186106250
.

[dunglas]

@soyuka take a look at https://github.com/dunglas/DunglasApiBundle/tree/master/tests/Fixtures/TestBundle/Entity

[teohhanhui]

referring to e6c6c87

I'm not sure "API Platform Builder" makes sense. I thought the plan is to have something like symfony/symfony, so api-platform/api-platform?

[dunglas]

Not really. The idea is more to have something like the Laravel repository structure:

api-platform/api-platform will stay as a preinstalled edition of a working framework (as it is now), and it will depends of api-platform/builderand api-platform/schema-generator (and maybe others like api-platform/tester in some times).

[teohhanhui]

Uhh... But "builder" still doesn't make sense to me, taking into account my experience with the bundle so far.

[dunglas]

@teohhanhui I'm open to suggestions for a better name (/cc @sroze @theofidry)

[teohhanhui]

Core? Engine? :stuck_out_tongue:

[dunglas]

It's very generic. Builder reflects what this library does: it helps building APIs.

[soyuka]

An engine helps a car to run, here the api-platform/engine makes api-platform/api-platform run. Seems fair too. Thanks about the link!

[teohhanhui]

It's what powers the API Platform, hence engine. Like "Google App Engine". Maybe we can go with api-platform/api-engine...

Builder gives the mental image of a scaffolding tool, like the schema-generator (which is actually not a schema generator, but a scaffolding tool taking schema as input :stuck_out_tongue:)

[theofidry]

I also prefer Engine to Builder as I think it talks more to people. Although not completely satisfied with the name... but can't find much better myself.

[sroze]

Anyway, let's be honest that Builder or Engine (or even Core) are
meaningless anyway. I'm finally quite in favour of using the "Symfony way".
Rename this one to api-platform and api-platform to symfony-edition,
that way it also allows us to think about a silex or laravel edition.
On Fri, 19 Feb 2016 at 09:47, Théo FIDRY [email protected] wrote:

I also prefer Engine to Builder as I think it talks more to people.
Although not completely satisfied with the name... but can't find much
better myself.

—
Reply to this email directly or view it on GitHub
https://github.com/dunglas/DunglasApiBundle/issues/376#issuecomment-186141948
.

[dunglas]

@sroze I stongly prefer the Laravel way. If you want to use API Platform, just run composer create-project api-platform/api-platform. You'll get a working skeleton with all default choices (like using Symfony) done for you.

For a Laravel or Silex edition, we can create repositories like api-platform/laravel-edition... but it's very unlikely that such edition becomes the default (because Symfony rocks 😆).

[jo-victor]

Same here, for me Builder means a scaffolding tool, I prefer api-platform/core.

[dunglas]

Let's vote: http://doodle.com/poll/8wz7znhbi2g2kczc

[soyuka]

When I hear "Builder" I'm thinking "Worker" (the guy that builds our houses). When I hear "Engine", "Core" or even "Diesel" ("Dynamo"), I'm automatically picturing a nice tool that makes our lives better :).

+1 symfony rocks, laravel users are hipsters \o/

[theofidry]

\o/

[theofidry]

laravel users are hipsters \o/

Don't say that, we don't always get to choose...

[theofidry]

@dunglas could we put multichoice instead? Also you did not include @sroze suggestion even if you think it's unlikely :)

[soyuka]

@theofidry joking ofc, I'm familiar with the "you don't have a choice" ;)

[dunglas]

To be fair there are a lot of excellent ideas in Laravel.

[sroze]

@dunglas could we put multichoice instead? Also you did not include @sroze suggestion even if you think it's unlikely :)

:+1:

[soyuka]

To be fair there are a lot of excellent ideas in Laravel.

And also bad design choices. Never did a full project with it but as far as I remember I felt bad using so many statics...

[theofidry]

There is a lot of choices to make it more simple even if it comes with the price of being less testable and flexible at some times. But if you want to build it right you still can, after all it's just a tool, you're the one building the software right?

That being said let's not debate about that I can already hear jakzal coming ranting against Laravel :p

[3kynox]

As I voted up, and doesn't matter if it looks symfony / or laravel way, is to name this bundle core, as it permit to connect another features or more decoupled things to the core and extends possibilties to a long-term period.

[teohhanhui]

I'm not so keen about the word "core" because we'll then keep getting into the argument of what's core and what's not core. It gives the wrong idea because it's not meant to be _just_ the core parts, but actually a collection of disparate components that work together (much like Symfony)...

[dunglas]

I've opened the PR renaming the lib according to results of the poll: #424
Please review.

[3kynox]

@dunglas said : As you can see, most of the work is now done. Last but not least: updating the doc.

I'll have some free time soon and will work on documentation. I will have for sure questions about new v2 usage but will definitely help with this.

[vinset]

Hi Dunglas,
when version 1.1 will be released?

[dunglas]

As FOSUser v1 will not be compatible with Symfony 3. Our tests will not pass with Symfony 3 as well (even if the bundle itself is compatible).

So I think we can release the 1.1 version asap. What do you think @api-platform/core-team?

[theofidry]

@dunglas considering we have it in beta for some time already, think it's worth it although it's a pity it can't be used with FOSUserBundle in Symfony3. So :+1: for me

[vinset]

Any news for 1.1?

[theofidry]

Soon :) We are just fixing a few things for Symfony 3 compatibility and merging a few last features before releasing it. But a new beta version should be out at the end of the week.

[vinset]

Thanks for reply!

[rafix]

What is the recommended version to start a long term project?
1.1.x
2.0-dev

[dunglas]

It depends...

1.1 is stable and used in many projects in production. It has a good documentation.

2.0 has a better design, is easier to use. is more extensible and more decoupled, but it's still experimental, it depends of Symfony 3.1 (still in dev), of PHP 7 and its doc is still a WIP.

If you are ready to deal with youth issues and don't have a short dead line, use v2. In other cases use v1.

[soyuka]

@dunglas when the yml/xml parsing is done in v2 (I've started some experiments), are you considering a compatibility layer with v1 resource declarations?

[dunglas]

If someone contribute it and if it is stable enough to be integrated in core yes of course.

[dunglas]

@vinset 1.1 beta 2 has been tagged today: https://twitter.com/ApiPlatform/status/715167459549061121

If no problem is reported, I'll tag the stable release Wednesday.

[vinset]

I want to test this version. Can I install 1.1 beta via composer? If yes, how?

[theofidry]

@vinset composer require "api-platform/core:~1.1@beta"

[vinset]

Today is a 1.1 stable day? :+1:

[vinset]

Hi api-platform team! Any news about the release of 1.1 stable?

[tacman]

What is the best approach for those of us who want to use Symfony 3.1 and API-Platform?

[dunglas]

@tacman Use v2!

[tacman]

Thanks -- I thought it was still in alpha. We'll give it a try!

[dunglas]

It is but the code is almost ready (and we already use it in production). The main missing part is the doc (but it is being completed: https://github.com/api-platform/doc)

[soyuka]

I find it even more _stable_ then v1, I mean it feels more rock-solid. Even for an alpha version 😆

[dunglas]

All steps have been done. I'll release the 2.0.0 in the end of August (when I'll be back home).