Advanced Configuration

Calling Without Version

This is the most common call you will make... which is without any particular version (to the default version in the IO State). This would look like the following:

http://localhost:8080/v1.0/person/create

Calling With Version

If you have a particular version you wish to call (and you know it is supported via documentation), simply call that version of the endpoint like so:

http://localhost:8080/v1.0-1/person/create

Calling With App Version

If you are running separate application versions and are properly routing based on app version, simply call the different app version like so:

http://localhost:8080/v0.5/person/create

... or like so:

http://localhost:8080/v0.5-1/person/create

Variable Declaration

Lets break apart the pieces of an IOState file to see what they consist of and how they work; the first part of the file declares 'VALUES' for use by the endpoints:

    "NAME":"person",
    "NETWORKGRP": "public",
    "VALUES": {
        "id": {
            "key": "PRIMARY",
            "type": "Long",
            "description":"ID for Event",
        "mockData":"1"
        },
        "version": {
            "type": "Long",
            "description":"Version for Event",
        "mockData":"0"
        },

        ...

We start by declaring the NAME of the file and our 'values':

• NAME: This corresponds directly with the name of the controller; the controller typically pulls in from the same domain name but does not have to. The controller can create a nested call, return a file, etc. So the name directly relates to the controller.
• NETWORKGRP: This defines the 'networkGroup' that this group of endpoints can be accessed through thus defining the CORS allowed origins and the ROLES that can access it. See Security section for more
• VALUES: These are the individual variables returned. These help us for automating testing, api docs and defining what needs to be sent and returned in each endpoint.

Underneath values, then define each individual value to be sent/returned with the following stats:

• type (required) : One of [PKEY, FKEY, INDEX, STRING, DATE, LONG, BOOLEAN, FLOAT, BIGDECIMAL, EMAIL, URL, ARRAY, COMPOSITE]. Defines scope of variable; only used for apidocs/options or for reference.
• description (required) : description of variable, how it is used; mainly for apidocs
• references (optional) : This allows someone to point a PKEY/FKEY/Index to its referencing IO State Object NAME. Usage is as follows:
  • references: self (type:Long): primary key, reference to self;
  • references: <name of API Object referenced w/ type:Long> (type:Long): foreign key; referenced to IO State Object
  • references: <name of API Object referenced w/ type:String> (type:String): index;reference to IO State Object
• mockData(required) : string descriptor; Mock data for tests and apidoc.

Rules Declaration

Following this, we then define the 'rules' for our endpoints in the IOState like so:

    "CURRENTSTABLE": "1",
    "VERSION": {
        "1": {
            "DEFAULTACTION":"list",
            "URI": {
                "create": {
                    "METHOD":"POST",
                    "DESCRIPTION":"Create new Person",
                    "ROLES":{
                        "DEFAULT":["ROLE_ADMIN","ROLE_USER"],
                        "BATCH":["ROLE_ADMIN"],
                        "HOOK":["ROLE_ADMIN"]
                    },
                    "REQUEST": {
                        "permitAll":["username","password","email"]
                    },
                    "RESPONSE": {
                        "permitAll":["id","version"]
                    }
                },
                ...

The above data has the following definitions:

• CURRENTSTABLE: This is the current stable version of IOState; if you you do not have multiple versions of this file, this number is the same as 'VERSION'
• VERSION: This is the file version. This allows to API to have several versions of IOState if you are currently supported deprecated versions
  • DEFAULTACTION: This is the default endpoint action if if none given; commonly 'list'
  • DEPRECATED: (OPTIONAL) Formated a MM/DD/YYYY, this field represents when this api version goes 'stale' and can no longer be used
  • URI: This is the endpoint and the rules for the endpoint.

Then under 'URI', you define the rules for the endpoint for the controller/method. In this case for the NAME 'person' and URI 'create' point to the controller method 'person.create', which would be called like so:

http://<yourdomain>:8080/v1.0/person/create

We will explain more about where the 'v1.0' comes under 'Versioning' but for right now, lets finish explaining the rest of the IOState:

• METHOD: One of [GET, PUT, POST,DELETE]. This defines how the endpoint should be called.
• DESCRIPTION: A description of the endpoint for the API Docs
• ROLES: A grouping for security rules (SEE 'Security: Network Roles')
• BATCH: Security roles for endpoints that have batching enabled
• HOOK: Security roles for endpoints that have web hooks enabled
• REQUEST: Per role data for expected when sending the request; concatenates across roles
• RESPONSE: Per role data for expected when sending the request; concatenates across roles

"REQUEST": {
    "permitAll":["name"],
    "ROLE_USER":["id"]
},

Empty PermitAll

If you are sending no values (such as a 'list' call) or returning no values, you will often have an empty 'permitAll' such as the following:

"REQUEST": {
    "permitAll":[]
},

An empty 'permitAll' should NEVER be declared with quotes as this sends an empty string. Always leave the brackets empty like above to declare that nothing needs to be sent.