Options

Table of Contents

1. Preamble
2. Options manifest
   1. Version
   2. Name
   3. Unique
   4. Collection
      1. Allowed methods
      2. Requestable properties
      3. Allow complex request
      4. Limit
3. Inheritance
4. Autoloading
5. Override comhon options
6. Options Person example

Preamble

Options are defined in a manifest file and are attached to a model. They permit to allow or not some settings on objects requests. Request validation is done when executing request with requester and when using REST API.

Options are optional, by default all settings and actions are available.

Options manifest

Options manifests may be defined in XML, JSON or YAML format (depends on manifest format defined in Configuration file). The Options correspond to model Comhon\Options described by manifest here. For each explanation example we will illustrate XML and JSON format. YAML is quite same as JSON, we will only write a complete example at the end.

Version

In this file you have to specify the options manifest version. There is currently one allowed version 3.0.

<root version="3.0"/>

{
    "version": "3.0"
}

Name

You have to specify the manifest name. The name must be a fully qualified name, in other words it must contain namespace.

<root version="3.0" name="Test\Person"/>

{
    "version": "3.0",
    "name": "Test\\Person"
}

Warning! due to JSON format you have to put double slash (\\).

Unique

unique node contain the informations on available HTTP methods on a unique given resource (By default all methods are available). It is used when HTTP request URI contains the resource identifier.
For example :

GET https://www.mydomain.com/api/person/10

PUT https://www.mydomain.com/api/person/10

To available only PUT and GET request, options should look like :

<root name="Sample\Person" version="3.0">
  <unique>
    <allowed_methods>
      <method>GET</method>
      <method>PUT</method>
    </allowed_methods>
  </unique>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "unique": {
        "allowed_methods": [
            "GET",
            "PUT"
        ]
    }
}

Collection

collection node contain the informations on available request setting when HTTP request URI doesn't contain the resource identifier.

Warning!!! collection name may be confusing because it doesn't concern only objects collection, it concern also resource creating, actually when creating resource you must not specify the id in URI.

For example, following request doesn't contain the resource identifier and describe unique resource.

POST https://www.mydomain.com/api/person

Allowed methods

It works exactly like in unique node.

<root name="Sample\Person" version="3.0">
  <collection>
    <allowed_methods>
      <method>GET</method>
    </allowed_methods>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "allowed_methods": [
            "GET"
        ]
    }
}

Requestable properties

Requestable properties permit to limit properies that may be part of request filter. For example, On model Sample\Person you may allow filter only on firstName and lastName. the Options may look like :

<root name="Sample\Person" version="3.0">
  <collection>
    <requestable_properties>
      <name>firstName</name>
      <name>lastName</name>
    </requestable_properties>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "requestable_properties": [
            "firstName",
            "lastName"
        ]
    }
}

Allow complex request

To request object collections via HTTP request, there is two way :

• using request query parameters
• using request body

complex request might be defined only in request body.
The allow_complex_request node permit to allow or not complex requests.

<root name="Sample\Person" version="3.0">
  <collection allow_complex_request="0"/>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "allow_complex_request": false
    }
}

Limit

You can limit return collection length even if there is not limit defined in request.

<root name="Sample\Person" version="3.0">
  <collection limit="20"/>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "collection": {
        "limit": 20
    }
}

Inheritance

Unlike serialization, there is no inheritance for options. If you want same options on inherited models, you must redefine options. Basically if you want to define requestable properties, you must specify properties of current model and properties of parent model(s).

Autoloading

As manifests, options manifests are autoloaded. All options manifests files must be named options.json or options.xml (depends on manifest format defined in Configuration file).

By default Comhon! will search options manifest file in same folder than manifest file.
For example if manifest is at :

/my/directory/manifests/Person/manifest.json

Comhon! will search serialization manifest at :

/my/directory/manifests/Person/options.json

If you want to store options manifests in a different directory than manifest you can do so by specifying a directory for options manifests in Configuration file.

For example :

"autoload": {
  "manifest":{
    "Test":"../manifests/manifest"
  },
  "options":{
    "Test":"../manifests/options"
  }
}

manifests in namespace Test are stored in directory :

../manifests/manifest

options manifests in namespace Test are stored in directory :

../manifests/options

Override comhon options

You can override options files for comhon models (models prefixed by Comhon). You can find manifests here and options manifests here.

• First, you have to redefine in configuration file the path to your own comhon models options.

Example :

{
  "manifestFormat": "json",
  "autoload": {
    "manifest":{
      "Test":"../manifests/test/manifest"
    },
    "serialization":{
      "Test":"../manifests/test/serialization"
    },
    "options":{
      "Test":"../manifests/test/options",
      "Comhon":"../manifests/comhon/options"
    }
  }
}

• Second, you have to create options files in new defined directory. Be careful, you have to redefine all manifests options if you add Comhon prefix. Even if you just want to modify one, you have to copy/past others. If you don't redefine all manifest options, by default all settings and actions will be available for not redefined manifest options.

Example :
Model Comhon\Manifest options only allow GET, HEAD, OPTIONS methods for unique request URI. You might want to allow manifest creation and allow POST method for collection request URI.
So you have to create file ../manifests/comhon/options/Manifest/options.json and it should contain :

{
    "name": "Comhon\\Manifest",
    "version": "3.0",
    "unique": {
        "allowed_methods": [
            "GET",
            "HEAD",
            "OPTIONS"
        ]
    },
    "collection": {
        "allowed_methods": [
            "POST"
        ]
    }
}

and don't forget to redefine others options manifests.

Options Person example

<root name="Sample\Person" version="3.0">
  <unique>
    <allowed_methods>
      <method>GET</method>
      <method>PUT</method>
    </allowed_methods>
  </unique>
  <collection limit="20">
    <allowed_methods>
      <method>GET</method>
    </allowed_methods>
    <requestable_properties>
      <name>firstName</name>
      <name>lastName</name>
    </requestable_properties>
  </collection>
</root>

{
    "name": "Sample\\Person",
    "version": "3.0",
    "unique": {
        "allowed_methods": [
            "GET",
            "PUT"
        ]
    },
    "collection": {
        "allowed_methods": [
            "GET"
        ],
        "limit": 20,
        "requestable_properties": [
            "firstName",
            "lastName"
        ]
    }
}

name: Sample\Person
version: '3.0'
unique:
    allowed_methods: 
        - GET
        - PUT
collection:
    allowed_methods:
        - GET
    limit: 20
    requestable_properties:
        - firstName
        - lastName