New getting started #109

dunglas · 2016-09-19T15:31:47Z

WIP

meyerbaptiste · 2016-09-20T13:23:50Z

tutorial/api.md


-* empty the `app/config/schema.yml` file
-* delete all PHP files in the `src/AppBundle/Entity/` directory
+Start by [downloading the API Platform Standard Edition](https://api-platform.com/download) and extract the content of the


Is there a plan to update this page? As naive user, when I am on this page I see composer create-project api-platform/api-platform my-project or a link to https://github.com/api-platform/api-platform but no archive. It's confusing.

Yes! I'll do it when the new doc will be ready.

dunglas · 2016-09-21T20:50:05Z

Ping @api-platform/core-team, the main new tutorial is ready to be reviewed.

soyuka · 2016-09-22T06:01:29Z

tutorial/api.md


-Let's start our new blog API project. The easiest way to create a new project is to use [Composer](https://getcomposer.org/)
-(you need to have it installed on your box):
+API Platform is shipped with a entire [Docker](https://docker.com) setup that makes it easy to get a containerized development


with a ~~entire~~ Docker setup

soyuka · 2016-09-22T06:03:50Z

tutorial/api.md

-Let's start our new blog API project. The easiest way to create a new project is to use [Composer](https://getcomposer.org/)
-(you need to have it installed on your box):
+API Platform is shipped with a entire [Docker](https://docker.com) setup that makes it easy to get a containerized development
+environment up and running. This setup contains an image pre-configured with PHP 7, Apache and everything needed to run API


btw stack could be simplified with php-fpm (nothing to do with the getting-started guide though)

Yes, PR welcome!

Ok, if we remove apache php-fpm will listen on an upstream (like localhost:8080). Is it sufficient or you'd prefer having localhost (eg nginx proxy on top)?

soyuka · 2016-09-22T06:05:11Z

tutorial/api.md


-    composer create-project api-platform/api-platform:dev-master blog-api
+*Alternatively to using Docker, API Platform can also be installed using [Composer](https://getcomposer.org/):
+`composer create-project api-platform/api-platform bookshop-api`.*


As an alternative to Docker, API Platform can also be installed using Composer:

composer create-project api-platform/api-platform bookshop-api

Why emphasis?

It's italic.

Why italic ? :P

soyuka · 2016-09-22T06:06:51Z

tutorial/api.md

+`composer create-project api-platform/api-platform bookshop-api`.*

-Composer creates the skeleton of the new blog API then retrieve the framework and all its dependencies.
+Start by [downloading the API Platform Standard Edition](https://api-platform.com/download) and extract the content of the


...and extract it's content.

soyuka · 2016-09-22T06:09:10Z

tutorial/api.md

-Composer creates the skeleton of the new blog API then retrieve the framework and all its dependencies.
+Start by [downloading the API Platform Standard Edition](https://api-platform.com/download) and extract the content of the
+archive.
+The resulting directory contains an empty API Platform project structure. You will add your own code and configuration inside


I'm not sure this sentence is needed as we repeat "go inside the directory containing your project skeleton" below

IMO It's less clear without it.

soyuka · 2016-09-22T06:24:48Z

tutorial/api.md

+and is very useful for open data, SEO and interoperability when [used with open vocabularies such as Schema.org](http://blog.schema.org/2013/06/schemaorg-and-json-ld.html).
+JSON-LD enables a lot of awesome advanced features (like [giving access to Google to your structured data](https://developers.google.com/search/docs/guides/intro-structured-data)
+or consuming APIs with [Apache Jena](https://jena.apache.org/documentation/io/#formats)).
+Wwe think that it's the best default for a new API. However, API Platform natively [supports many other formats](../core/content-negotiation.md)


We think that it's the best default format for a new API. However, API Platform natively supports many other formats

soyuka · 2016-09-22T06:25:18Z

tutorial/api.md

-Thanks to [NelmioApiDocBundle](https://github.com/nelmio/NelmioApiDocBundle) support of ApiBundle and its integration
-with API Platform, you get for a free **an automatically generated human-readable documentation** of the API (Swagger-like).
-The doc also **includes a sandbox** to try the API.
+There is 2 interesting things to mention about this request:


soyuka · 2016-09-22T06:26:13Z

tutorial/api.md

+it. You can use this IRI to reference this document from other documents. In the previous request, we used the IRI of the
+book we created earlier to link it with the `Review` we were creating. API Platform is smart enough to deal with IRIs.
+By the way, you may want to [embed documents](../core/serialization-groups-and-relations.md) instead of referencing them (e.g. to reduce the number of HTTP requests
+to issue).


(e.g. to reduce the number of HTTP requests ~~to issue~~).

soyuka · 2016-09-22T06:32:35Z

tutorial/api.md

-```
+Did you notice that the error was automatically serialized in JSON-LD and respect the Hydra Core vocabulary for errors?
+It allows the client to easily extract useful information from the error. Anyway, it's bad to get a SQL error when submitting
+a request. It means that we doesn't valid use input, and [it's a very bad and dangerous practice](https://www.owasp.org/index.php/Input_Validation_Cheat_Sheet).


It means that we doesn't use a valid input,

soyuka · 2016-09-22T06:33:19Z

tutorial/api.md

-The API Platform flavor of Behat also comes with a temporary SQLite database dedicated to tests. It works out of the box.
-
-Simply run `vendor/bin/behat`. Everything should be green:
+After updating the entities to add those `@Assert\*` annotations (as for Doctrine, you can use XML or YAML formats if you


by adding those @Assert\* annotations

theofidry · 2016-09-22T15:42:03Z

core/getting-started.md

 ```

-There is no mandatory configuration. However, a lot of [configuration parameters](configuration.md) are available.
+There is no mandatory configuration. However, a bunch of [configuration parameters](configuration.md) are available.


There is no mandatory configuration although some parameters are configurable.

theofidry · 2016-09-22T15:42:59Z

tutorial/api.md

-
-To follow this tutorial a database must be installed (but its not a strong dependency of the framework). We recommend MySQL
-or MariaDB but other major DBMS are supported including PostgreSQL and SQLite.
+[API Platform](https://api-platform.com) is the most efficient framework out there to create web APIs. It makes it


is the most efficient modern PHP framework to create web APIs.

It changes the meaning of the sentence ;)

It's a marketing sentence. Someone can argue that Apigility or FOSRest or anything else is more efficient. Someone can also argue that Django REST or Loopback is more efficient. It's just subjective marketing :)

I don't think marketing belongs in the documentation. It's a very bold claim and it makes me feel uncomfortable as a reader when I see such expletives.

We can use adjectives, but expletives should be avoided.

Can you suggest an alternative wording? What do you think about "API Platform is one the most efficient framework out there to create web APIs."?

We can keep the "best in the world" or "best framework out there" part in the homepage, let's be more neutral for the doc :P

API Platform is a framework for creating modern web APIs efficiently.

teohhanhui · 2016-09-26T11:55:35Z

core/getting-started.md

 ```

-There is no mandatory configuration. However, a lot of [configuration parameters](configuration.md) are available.
+There is no mandatory configuration configuration although [some parameters](configuration.md) are configurable.


configuration ~~configuration~~

Configuration != parameters in Symfony speak. We should not use terms that may lead to confusion.

teohhanhui · 2016-09-26T11:59:16Z

tutorial/api.md

-
-To follow this tutorial a database must be installed (but its not a strong dependency of the framework). We recommend MySQL
-or MariaDB but other major DBMS are supported including PostgreSQL and SQLite.
+[API Platform](https://api-platform.com) is the most efficient framework out there to create web APIs. It makes it


I don't think marketing belongs in the documentation. It's a very bold claim and it makes me feel uncomfortable as a reader when I see such expletives.

teohhanhui · 2016-09-26T11:59:54Z

tutorial/api.md

-
-To follow this tutorial a database must be installed (but its not a strong dependency of the framework). We recommend MySQL
-or MariaDB but other major DBMS are supported including PostgreSQL and SQLite.
+[API Platform](https://api-platform.com) is the most efficient framework out there to create web APIs. It makes it


We can use adjectives, but expletives should be avoided.

teohhanhui · 2016-09-26T12:00:31Z

tutorial/api.md

-To follow this tutorial a database must be installed (but its not a strong dependency of the framework). We recommend MySQL
-or MariaDB but other major DBMS are supported including PostgreSQL and SQLite.
+[API Platform](https://api-platform.com) is the most efficient framework out there to create web APIs. It makes it
+easy to create simple APIs with support of industry leading open standards while giving you the ability to create complex


~~simple~~ APIs

This gives the wrong idea.

with the support of

teohhanhui · 2016-09-26T12:03:19Z

tutorial/api.md

-or MariaDB but other major DBMS are supported including PostgreSQL and SQLite.
+[API Platform](https://api-platform.com) is the most efficient framework out there to create web APIs. It makes it
+easy to create simple APIs with support of industry leading open standards while giving you the ability to create complex
+features with style. To discover the basics, we will create an API to manage a bookshop.


create complex features with style?

I'm not sure what this part of the sentence is trying to say...

Perhaps we should rephrase this sentence to something like this:

It makes it easy to start creating APIs with the support of industry-leading open standards, while giving you the flexibility to build complex features.

teohhanhui · 2016-09-26T12:17:46Z

tutorial/api.md

+* filtering
+* sorting
+* content negotiation
+* a nice UI and machine-readable documentations ([Swagger/OpenAPI](https://swagger.io), [Hydra](http://hydra-cg.com))


documentation (uncountable)

teohhanhui · 2016-09-26T12:24:42Z

tutorial/api.md


-While API Platform is perfectly integrated with Symfony, keep in mind that it's basically a set of standalone PHP components.
-You can also use those components in raw PHP (without framework) as well as with other frameworks.
+If you're used to the PHP ecosystem, you probably guessed that this test entity uses the industry leading [Doctrine ORM](http://www.doctrine-project.org/projects/orm.html)


industry-leading

dunglas · 2016-09-29T12:54:46Z

This PR is ready now. Can you review please?

dunglas changed the title ~~New getting started~~ [WIP] New getting started Sep 19, 2016

meyerbaptiste reviewed Sep 20, 2016

View reviewed changes

soyuka requested changes Sep 22, 2016

View reviewed changes

theofidry reviewed Sep 22, 2016

View reviewed changes

teohhanhui reviewed Sep 26, 2016

View reviewed changes

teohhanhui mentioned this pull request Sep 27, 2016

YAML needs to be api_resource.yml not resource.yml #114

Merged

dunglas and others added 12 commits September 29, 2016 14:51

wip

9e69a5d

[WIP] Rewrite the getting started guide

3b628d6

some more changes

8ccd25f

Fix syntax & typo

e1b5759

Fix entities

c4ccf41

wip

37debf6

wip

ebb5e9c

some more changes

ffb74ae

hotfix: update resource filename for yml & xml

49a0166

Fix @soyuka and @theofidry

1388696

Address @soyuka and @teohhanhui's comments

eb54145

Add a test example

4740bd1

dunglas force-pushed the new_getting_started branch from 5d2188e to 4740bd1 Compare September 29, 2016 12:54

dunglas changed the title ~~[WIP] New getting started~~ New getting started Sep 29, 2016

soyuka approved these changes Sep 29, 2016

View reviewed changes

vincentchalamon approved these changes Sep 29, 2016

View reviewed changes

dunglas merged commit 6f20cf5 into api-platform:master Sep 30, 2016

dunglas deleted the new_getting_started branch September 30, 2016 08:15

Uh oh!

New getting started #109

New getting started #109

Uh oh!

Conversation

dunglas commented Sep 19, 2016

Uh oh!

meyerbaptiste Sep 20, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas commented Sep 21, 2016

Uh oh!

soyuka Sep 22, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soyuka Sep 23, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soyuka Sep 22, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

teohhanhui Sep 26, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

meyerbaptiste Sep 20, 2016 •

edited

Loading

soyuka Sep 22, 2016 •

edited

Loading

soyuka Sep 23, 2016 •

edited

Loading

soyuka Sep 22, 2016 •

edited

Loading

teohhanhui Sep 26, 2016 •

edited

Loading

teohhanhui Sep 26, 2016 •

edited

Loading