JsonApiBundle For Symfony
JsonApiBundle is a Symfony bundle. It is the fastest way to generate API based on JsonApi
using woohoolabs/yin Library.
Installing
Install symfony
composer create-project symfony/skeleton YOUR_PROJECT
Install the maker bundle
composer require symfony/maker-bundle phootwork/collection --dev
Install the bundle
composer require paknahad/jsonapi-bundle
Add below line to
config/bundles.php
Paknahad\JsonApiBundle\JsonApiBundle::class => ['all' => true],
Usage
Use below command to generate entities one by one:
bin/console make:entity
for example, Book and Author entity is as follows:
```php
class Book
{
/**
* @ORM\Id()
* @ORM\GeneratedValue()
* @ORM\Column(type="integer")
*/
private $id;/** * @ORM\Column(type="string", length=255) */ private $title; /** * @ORM\Column(type="string", length=20, nullable=true) */ private $isbn; /** * @ORM\ManyToMany(targetEntity="App\Entity\Author", inversedBy="books") */ private $authors; ...
```php class Author { /** * @ORM\Id() * @ORM\GeneratedValue() * @ORM\Column(type="integer") */ private $id; /** * @ORM\Column(type="string", length=255) * @Assert\NotBlank() * @Assert\Length(min=3) */ private $name; /** * @ORM\ManyToMany(targetEntity="App\Entity\Book", mappedBy="authors") */ private $books; ...
Generate CRUD API:
bin/console make:api
You can find the generated "collections" for postman and swagger in the following path and then test the API:
collection/postman.json
collection/swagger.yaml
Features
Pagination
http://example.com/books?page[number]=5&page[size]=30
Sorting
- Ascending on name field:
http://example.com/books?sort=name
- Decending on name field:
http://example.com/books?sort=-name
- Multiple fields:
http://example.com/books?sort=city,-name
- Field on a relation:
http://example.com/books?sort=author.name
Relationships
http://example.com/books?include=authors
multiple relationships
http://example.com/books?include=authors.phones,publishers
Search
As the JSON API specification does not specify exactly how filtering should work different methods of
filtering can be used. Each method is supplied with a Finder service. Each registered Finder will be able to append
conditions to the search query. If you register multiple Finders they are all active at the same time. This enables
your API to support multiple filtering methods.
Basic Finder.
A basic Finder is included in this library offering simple filtering capabilities:
This request will return all the books that author's name begin with hamid
http://example.com/books?filter[authors.name]=hamid%
Below line has additional condition: books which have "php" in their title.
http://example.com/books?filter[title]=%php%&filter[authors.name]=hamid%
Other Finders
Currently the following Finders are available via other bundles:
- mnugter/jsonapi-rql-finder-bundle - RQL based Finder
Creating a custom Finder
A Finder can be registered via a service tag in the services definition. The tag paknahad.json_api.finder
must be
added to the service for the Finder to be resigered.
Example:
<service class="Paknahad\JsonApiBundle\Helper\Filter\Finder" id="paknahad_json_api.helper_filter.finder">
<tag name="paknahad.json_api.finder" />
</service>
Each Finder must implement the Paknahad\JsonApiBundle\Helper\Filter\FinderInterface
interface.
Validation
Error on validating associations
json
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"detail": "Invalid value for this relation",
"source": {
"pointer": "/data/relationships/authors",
"parameter": "1"
}
}
]
}
Validate attributes if you have defined validators on entities.
json
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"detail": "This value is too short. It should have 3 characters or more.",
"source": {
"pointer": "/data/attributes/name",
"parameter": "h"
}
}
]
}
Security
This bundle generates a voter for each controller for checking permissions.
After making APIs you can find voters in src/Security
Error handler
All errors such as:
- Internal server error (500)
- Not found (404)
- Access denied (403)
has responses like this:
json
{
"meta": {
"code": 0,
"message": "No route found for \"GET /book\"",
"file": "/var/www/vendor/symfony/http-kernel/EventListener/RouterListener.php",
"line": 139,
"trace": [
{
"file": "/var/www/vendor/symfony/event-dispatcher/EventDispatcher.php",
"line": 212,
"function": "onKernelRequest"
},
{
"file": "/var/www/vendor/symfony/event-dispatcher/EventDispatcher.php",
"line": 44,
"function": "doDispatch"
},
{
"file": "/var/www/vendor/symfony/http-kernel/HttpKernel.php",
"line": 125,
"function": "dispatch"
},
{
"file": "/var/www/vendor/symfony/http-kernel/HttpKernel.php",
"line": 66,
"function": "handleRaw"
},
{
"file": "/var/www/vendor/symfony/http-kernel/Kernel.php",
"line": 188,
"function": "handle"
},
{
"file": "/var/www/public/index.php",
"line": 37,
"function": "handle"
}
]
},
"links": {
"self": "/book"
},
"errors": [
{
"status": "404",
"code": "NO_ROUTE_FOUND_FOR_\"GET_/BOOK\"",
"title": "No route found for \"GET /book\""
}
]
}
NOTICE: the "meta" field gets filled just on development environment.
Copyright (c) 2018 Hamid Paknahad
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
-
make the tests compatible with new changes
By paknahad, 1 year ago
-
fix tiny issues
By paknahad, 1 year ago
-
refactor Hydrators & ResourceTransforms
By paknahad, 1 year ago
-
checking authority on filtering. fix #22
By paknahad, 1 year ago
-
Update ResourceCollection.php
By paknahad, 1 year ago
-
fix composer's file
By paknahad, 1 year ago
-
update readme
By paknahad, 1 year ago
-
Improve Exception handler
By paknahad, 1 year ago
-
modify all templates for checking by voters
By paknahad, 1 year ago
-
add InputOutputManager
By paknahad, 1 year ago
-
init security service
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
#17
By paknahad, 1 year ago
-
fix generated abstractHydrator
By paknahad, 1 year ago
-
fix hydrator validator.
By paknahad, 1 year ago
-
Add an IO transformer. fix 2nd from #13
By paknahad, 1 year ago
-
fix the hydrator's validator.
By paknahad, 1 year ago
-
Fix incorrect Finder class location and Request class #9
By paknahad, 1 year ago
-
Update README to describe the new Finder strategy #11
By paknahad, 1 year ago
-
Support more advanced filtering in query #5
By paknahad, 1 year ago
-
add basic validator to hydrators
By paknahad, 1 year ago
-
change php version & remove unused dependency. fix #6
By paknahad, 1 year ago
-
fix postman urls
By paknahad, 1 year ago
-
fix setId of abstract hydrator. fix #4
By paknahad, 1 year ago
-
update readme
By paknahad, 1 year ago