ongr-io / apibundle

ONGR API Bundle

ONGR Api Bundle

Api Bundle allows rapid setup of RESTful API to simplify Elasticsearch data access for the remote clients.

Documentation

The source of the documentation is stored in the Resources/doc/ folder in this bundle.

Read the API Bundle Documentation

Setup the bundle

This example assumes that you already have configured Elasticsearch bundle. If you haven't, here's a quick setup guide on how to do it.

Step 1: Install

Api bundle is installed using Composer.

composer require ongr/api-bundle "~1.0"

Step 2: Enable bundle in the AppKernel

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new JMS\SerializerBundle\JMSSerializerBundle(),
        new ONGR\ElasticsearchBundle\ONGRElasticsearchBundle(),
        new ONGR\ApiBundle\ONGRApiBundle(),
    );
}

API Bundle requires JMS Serializer to work with JSON and XML

Step 3: Add configuration

Add minimal configuration for Api bundle to the config.yml.

#app/config/config.yml

ongr_api:
    default_encoding: json
        versions:
            v3:
                endpoints:
                    product:
                        repository: es.manager.default.product

The example above shows a minimal configuration. To learn more take a look at the configuration page.

Add routing

#app/config/routing.yml

ongr_api_routing:
    resource: @ONGRApiBundle/Resources/config/routing.yml
    prefix: /api

You can specify prefix like you want, api is only the example.

Step 4: That's it

Its ready to use. API Bundle will generate new url endpoints by your configuration, by previous configuration you will have: <yourdomain.com>/api/v3/product

What's next ?

Head to configuration page to learn how to get most of your API or take a look at the basic usage example

License

This bundle is covered by the MIT license. Please see the complete license in the bundle LICENSE file.

apibundle's Issues

Finish DataRequestSerive

Implement getAll action in RestController

More info: https://github.com/ongr-io/ApiBundle/blob/9610b53ea5bc7dd3390b4be27e7a94452a3e4cb8/Resources/doc/endpoints.md#get-all-documents

Check if all property types validation works

Refactor router extension

Router should search a match of generated API endpoint service by version and name.

Ability to run batch using messaging queue

Probably RabbitMQ

Make sure API will work with ElasticsearchBundle v1.0.0

Currently Elasticsearch bundle is in the alpha stage, but it's already more or less stable. So its about time to make sure it will work well with new version.

Write functional tests

We need to test:

• Multiple versions
• Custom controller
• Parent handling for endpoint
• Parent handling for version
• Config tree

Make sure correct routes are generated from the config in DI Extension

Look at the configuration docs: https://github.com/ongr-io/ApiBundle/blob/9610b53ea5bc7dd3390b4be27e7a94452a3e4cb8/Resources/doc/configuration.md

Say we have:

ongr_api:
   output_format: json
   version_in_url: true
   versions:
       v3:
           endpoints:
               person:
                   repository: es.manager.default.person
                   allow_extra_fields: false
                   allow_get_all: true

Routes we expect to have generated dynamicaly:
/api/v1/person POST
/api/v1/person/{id} PUT
/api/v1/person/{id} GET
/api/v1/person/_all GET
/api/v1/person/{id} DELETE
/api/v1/person/_batch POST

Routes must be pointed to specific RestController action.

Simple authentication

Ability to add unknown field to mapping

Unknown fields should have index=not_analyzed.

There is a need to import object variations for specific endpoint

Basicaly it means there is a need to support relations for any document. I'm not so sure if that is reasonable to support it natively in API bundle. It's too complex to be tied to a products or some other domain. Curently we are trying to make it more universal version where we can provide an easy way to use Restful API for elasticsearch.

Create `BatchController` controller to handle batch request

This controller has to implement https://github.com/ongr-io/ApiBundle/blob/master/Resources/doc/endpoints.md#multiple-insert

Remove symfony forms dependency

Forms now are used for validate documents. Exchange it with symfony/validator or something more reliable. Symfony forms IMO is worst choice.

Update tests

Unnecessary configuration is required

When defining endpoint with custom controller manager and document still must be set but controller might not need those.

Update documentation according to newest bundle version.

Ability to run batch in background

Response should be sent immediately regarding if batch is complete or not. Status code should be 202.

It could be useful if request is large.

Write bundle usage documentation

Change default controller from string to array in config.

Also array keys in controller array should be changed to more intuitive. Instead of

controller:
    controller: AcmeTestBundle:CustomApi

could be, for example:

controller:
    name: AcmeTestBundle:CustomApi

Create response builder service

Create controller which generates docs

There is not clear task how it should be done. So we need to do a little research here.

All the details and proposals lets discuss here.

Add version parents to configuration

Add ?pretty

Could we add the pretty parameter to format the output. That would be very helpful for debugging.

Batch processor

Should handle batch api, provide user friendly error handling.

• Should use rest controller for handling requests. (don't forward requests, low performance)
• User Friendly errors

Add ability to extend endpoints from other versions.

Implement version recognition in Accept header

We should require format: application/vnd.ongr.v3+json

Elasticsearch API commands

Implement oAuth2 authentication for the endpoints.

Add ability to use DataRequestService in custom controllers.

Find a way how to validate date.

Now date is validated as string in here.
There should be a way how to handle c format or maybe read from mapping if set.

Implement `BatchProcessor`

If the endpoint has enabled batch option we should let import multiple documents for a single type via bulk. Investigate and implement it.

More info: https://github.com/ongr-io/ApiBundle/blob/9610b53ea5bc7dd3390b4be27e7a94452a3e4cb8/Resources/doc/endpoints.md#multiple-insert

There is no relation support

e.g. product/100/items

Fix failing tests.

Config validation

Check if document and manager exists

endpoint overriding

Endpoint overriding with default values should be possible.

Implement `RestController`

Provide standard support for CRUD actions.

Redundant batch paths

• Remove versioning and route prefix
• Version batch

Finish Include and exclude config

Filter routes

Find a way how to filter routes in BatchController.

Now hardcoded:

ApiBundle/Request/BatchProcessor.php

Line 64 in c56579a

$options = $this->getRouter()->match('/api/' . $restRequest->getVersion() . '/' . $action['path']);

Update documentation

Refactor endpoints for full Restful support

Investigate the need of `Request\RestRequest`, `Request\RestRequestFactory`, `Request\RestRequestProxy`

Do we need those classes to generate routes?

Blocks #94

Incorrect include/exclude field inheritance.

See here

ApiBundle/Tests/Unit/DependencyInjection/ONGRApiExtensionTest.php

Line 325 in 0ed82b1

// This is an issue include fields should have been inherited.

Update categoryTree in DI Configuration.

• Add info to nodes
• Update example according to most recent version

Create pre and post events for DataRequest service

Allow custom controller

Remove Collection controllers

Remove: AbstractCollectionController, CollectionController, CollectionControllerInterface

We will create for _batch and _all standalone controllers.

Multiple documents per endpoint support

include/exclude field inheritance in extension.

Parent endpoint must not be changed while appending its config, since parent itself is not always processed before child.

Create `GetAllController` controller to handle `_all` request

This controller has to implement: https://github.com/ongr-io/ApiBundle/blob/master/Resources/doc/endpoints.md#get-all-documents