Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

New getting started #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dunglas merged 12 commits into api-platform:master from dunglas:new_getting_started
Sep 30, 2016
Merged

Conversation

@dunglas
Copy link
Member

@dunglas dunglas commented Sep 19, 2016

WIP

@dunglas dunglas changed the title (削除) New getting started (削除ここまで) (追記) [WIP] New getting started (追記ここまで) Sep 19, 2016
tutorial/api.md Outdated

* 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
Copy link
Member

@meyerbaptiste meyerbaptiste Sep 20, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

dunglas commented Sep 21, 2016

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

tutorial/api.md Outdated

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
Copy link
Member

@soyuka soyuka Sep 22, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with a (削除) entire (削除ここまで) Docker setup

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, PR welcome!

Copy link
Member

@soyuka soyuka Sep 23, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)?

tutorial/api.md Outdated

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`.*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Why emphasis?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's italic.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why italic ? :P

teohhanhui reacted with thumbs up emoji
tutorial/api.md Outdated
`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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...and extract it's content.

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
Copy link
Member

@soyuka soyuka Sep 22, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO It's less clear without it.

tutorial/api.md Outdated
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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

tutorial/api.md Outdated
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are

tutorial/api.md Outdated
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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(e.g. to reduce the number of HTTP requests (削除) to issue (削除ここまで)).

tutorial/api.md Outdated
```
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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

tutorial/api.md Outdated
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

by adding those @Assert\* annotations

```
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.
Copy link
Contributor

@theofidry theofidry Sep 22, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no mandatory configuration although some parameters are configurable.

tutorial/api.md Outdated

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
Copy link
Contributor

@theofidry theofidry Sep 22, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It changes the meaning of the sentence ;)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can use adjectives, but expletives should be avoided.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."?

Copy link
Contributor

@theofidry theofidry Sep 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

teohhanhui reacted with thumbs up emoji
Copy link
Contributor

@teohhanhui teohhanhui Sep 27, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

```
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.
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

configuration (削除) configuration (削除ここまで)

Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

tutorial/api.md Outdated

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
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

tutorial/api.md Outdated

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
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can use adjectives, but expletives should be avoided.

tutorial/api.md Outdated
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
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(削除) simple (削除ここまで) APIs

This gives the wrong idea.

Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with the support of

tutorial/api.md Outdated
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.
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

create complex features with style?

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

Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

dunglas reacted with thumbs up emoji
tutorial/api.md Outdated
* filtering
* sorting
* content negotiation
* a nice UI and machine-readable documentations ([Swagger/OpenAPI](https://swagger.io), [Hydra](http://hydra-cg.com))
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

documentation (uncountable)

tutorial/api.md Outdated

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)
Copy link
Contributor

@teohhanhui teohhanhui Sep 26, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

industry-leading

@dunglas dunglas changed the title (削除) [WIP] New getting started (削除ここまで) (追記) New getting started (追記ここまで) Sep 29, 2016
Copy link
Member Author

dunglas commented Sep 29, 2016

This PR is ready now. Can you review please?

@dunglas dunglas merged commit 6f20cf5 into api-platform:master Sep 30, 2016
@dunglas dunglas deleted the new_getting_started branch September 30, 2016 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@meyerbaptiste meyerbaptiste meyerbaptiste left review comments

@vincentchalamon vincentchalamon vincentchalamon approved these changes

@soyuka soyuka soyuka approved these changes

+2 more reviewers

@teohhanhui teohhanhui teohhanhui left review comments

@theofidry theofidry theofidry left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /