https://github.com/demartis/symfony5-rest-api
API REST skeleton with Symfony 5, following best practices and implementing clean architecture.
https://github.com/demartis/symfony5-rest-api
api docker docker-compose fosrestbundle hateoas json-api php rest rest-api symfony symfony5 travis
Last synced: 2 months ago
JSON representation
API REST skeleton with Symfony 5, following best practices and implementing clean architecture.
- Host: GitHub
- URL: https://github.com/demartis/symfony5-rest-api
- Owner: demartis
- License: mit
- Created: 2020-03-30T11:18:51.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-20T16:57:17.000Z (almost 2 years ago)
- Last Synced: 2024-04-20T18:11:34.504Z (almost 2 years ago)
- Topics: api, docker, docker-compose, fosrestbundle, hateoas, json-api, php, rest, rest-api, symfony, symfony5, travis
- Language: PHP
- Size: 163 KB
- Stars: 43
- Watchers: 3
- Forks: 25
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Symfony 5 REST API skeleton
Symfony 5 + FOSRestBundle + JSON Standard responses + working example
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fdemartis%2Fsymfony5-rest-api?ref=badge_shield)
--------------------------------------
⚠️ PHP 8.x required. If your server is still running PHP 7.x switch to [php7](https://github.com/demartis/symfony5-rest-api/tree/php7) branch.
--------------------------------------
## Table of Contents
+ [About](#about)
+ [Getting Started](#getting_started)
+ [JTTP](#jttp)
+ [Contributing](#contributing)
+ [License](#license)
## About
Symfony 5 skeleton to build REST APIs, inclusive of:
- *FOSRestBundle* (friendsofsymfony/rest-bundle) to simplify the entire process
- *Hateoas Bundle* (willdurand/hateoas-bundle) that specifies relation types for Web links
- *Doctrine*
This project is compliant with:
- [Symfony Best Practices](https://symfony.com/doc/5.4/best_practices.html)
- [HATEOAS](https://restfulapi.net/hateoas/), [RFC5988 (web links)](https://tools.ietf.org/html/rfc5988), [JSON HAL Model](http://stateless.co/hal_specification.html)
- [JTTP](https://github.com/demartis/jttp)
- URIs versioning
These instructions will get you a copy of the project up and running on your local machine
for development and testing purposes.
### Prerequisites
What things you need to install the software and how to install them.
- PHP 8.x. For PHP 7 (7.2.5+) use branch `php7`
- [composer](https://getcomposer.org/download/)
- [symfony](https://symfony.com/doc/5.4/setup.html)
- docker (optional)
### Installing
```bash
git clone https://github.com/demartis/symfony5-rest-api/
cd symfony5-rest-api
cp .env.dist .env
## edit .env if needed
composer install
symfony server:start
```
### Installing (alternative with Docker)
```bash
git clone https://github.com/demartis/symfony5-rest-api/
cd symfony5-rest-api
cp .env.dist .env
## edit .env if needed
docker-compose build
docker-compose up
```
### Running the example
#### Install database
```bash
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate
```
#### Run local server with Symfony app
```bash
symfony server:start
```
#### Get with Curl
```bash
curl -H 'content-type: application/json' -v -X GET http://127.0.0.1:8000/v1/books
curl -H 'content-type: application/json' -v -X GET http://127.0.0.1:8000/v1/books/2
```
## JTTP: Coherent output formats
[JTTP](https://github.com/demartis/jttp) is the default protocol
General JTTP output format:
```json
{
"status": "success|error",
"code": "HTTP status code",
"message": "HTTP status message",
"data|error": {
"your data": "data or error field only in case of success or error"
}
}
```
Example - GET resource: GET /v1/books/1
```json
{
"status": "success",
"code": 200,
"message": "OK",
"data": {
"id": 1,
"title": "PHP & MySQL Novice to Ninja",
"_links": {
"self": {
"href": "/v1/books/1"
}
}
}
}
```
Example - GET collection: GET /v1/books
```json
{
"status": "success",
"code": 200,
"message": "OK",
"data": [
{
"id": 1,
"title": "PHP & MySQL Novice to Ninja",
"_links": {
"self": {
"href": "/v1/books/1"
}
}
},
{
"id": 2,
"title": "Head First PHP & MySQL",
"pages": 812,
"_links": {
"self": {
"href": "/v1/books/2"
}
}
}
]
}
```
Example - POST resource: POST /v1/books
JSON (any other field will be ignored):
```json
{
"data": {
"title": "New Book about PHP",
"pages": 123
}
}
```
Response:
```json
{
"status": "success",
"code": 200,
"message": "OK",
"data": {
"id": 3,
"title": "New Book about PHP",
"pages": 123,
"_links": {
"self": {
"href": "/v1/books/12"
}
}
}
}
```
Example - PUT resource: PUT /v1/books/1
JSON (any other field will be ignored):
```json
{
"data": {
"title": "Edit title",
"pages": 1000
}
}
```
Response:
```json
{
"status": "success",
"code": 200,
"message": "OK",
"data": {
"id": 1,
"title": "Edit title",
"pages": 1000,
"_links": {
"self": {
"href": "/v1/books/1"
}
}
}
}
```
Example - error: Resource not found: GET /v1/books/123123
```json
{
"status": "error",
"code": 404,
"message": "Not Found",
"error": {
"details": "Resource 123123 not found"
}
}
```
Example - error: Route not found: GET /wrongroute123
```json
{
"status": "error",
"code": 404,
"message": "Not Found",
"error": {
"details": "No route found for \"GET /wrongroute123\""
}
}
```
Example - 500 Internal Server Error
```json
{
"status": "error",
"code": 500,
"message": "Internal Server Error",
"error": {
"details": "Notice: Undefined variable: view"
}
}
```
Example - form error - POST /v1/books
```json
{
"data": {
"pages": 123
}
}
```
Response:
```json
{
"status": "error",
"code": 400,
"message": "Bad Request",
"error": {
"form": {
"title": "This value should not be blank."
}
}
}
```
Use Fork capability and edit at your own
1. Fork it ()
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -am 'Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a new Pull Request
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fdemartis%2Fsymfony5-rest-api?ref=badge_large)