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
• URIs versioning

JTTP Coherent output formats

Inspired by Jsend, we have set a similar very simple but more coherent and intelligible json format to wrap json responses.

It is called JTTP, and it is compatible with HATEOAS, RFC5988 and HAL standards. See examples below.

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

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

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