tinhlesc / symfony5-rest-api

API REST skeleton with Symfony 5, following best practices and implementing clean architecture.

Symfony 5 REST API skeleton

Symfony 5 + FOSRestBundle + JSON Standard responses + working example

Table of Contents

• About
• Getting Started
• Contributing

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
• HATEOAS, RFC5988 (web links), JSON HAL Model
• JTTP
• URIs versioning

JTTP Coherent output formats

JTTP is the default protocol

General JTTP output format:

{
    "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

{
    "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

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

{
    "data": {
        "title": "New Book about PHP",
        "pages": 123
    }
}

Response:

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

{
    "data": {
        "title": "Edit title",
        "pages": 1000
    }
}

Response:

{
    "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

{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error": {
        "details": "Resource 123123 not found"
    }
}

Example - error: Route not found: GET /wrongroute123

{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error": {
        "details": "No route found for \"GET /wrongroute123\""
    }
}

Example - 500 Internal Server Error

{
    "status": "error",
    "code": 500,
    "message": "Internal Server Error",
    "error": {
        "details": "Notice: Undefined variable: view"
    }
}

Example - form error - POST /v1/books

{
    "data": {
        "pages": 123
    }
}

Response:

{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error": {
        "form": {
            "title": "This value should not be blank."
        }
    }
}

Getting Started

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 7.2.5+
• composer
• symfony
• docker (optional)

Installing

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)

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

php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate

Get with Curl

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 

Using it as skeleton

Add notes about how to use the system.

Contributing

1. Fork it (https://github.com/demartis/symfony5-rest-api/fork)
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

License