Quiles Service Description Files

00_Quiles.md

Quiles Example

This Gist provides a prototype of what a @latticework/quiles configuration might look like. (see Goals)

Discovery

Discovery Path

1. http://services.my-company.com
2. http://todo.services.my-company.com
3. http://todo.services.my-company.com/resources/todos
4. http://todo.services.my-company.com/resources/todo/routines/new-todo

Notes

• For DNS configuration: May have separate endpoints for internal access: http://services.my-company.infra

Directory

http://services.my-company.com

My Company Services

Directory: http://services.my-company.com

Name	Location	Description
todo	http://todo.services.my-company.com	Provides TODO application services.

Service Description

Notes

Issues

1. $schema is used in Visual Studio, but is it a standard?
2. How should versions be handled?
3. Version is currently at resource level. Is that correct?
4. Should version be in path or in header? I like the idea of using either. But:
5. We need to use client contracts for access. (What about discovery?)

quiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/directory/schema#",  
  "uri": "http://services.my-company.com",
  "services": [
      {
        "uri": "http://todo.services.my-company.com",
        "description": {"$ref": "http://todo.services.my-company.com#"}
      }
    ]
}

Directory

Property	Description
$schema	Specifies conforming JSON Schema
uri	For DNS: URL of directory
	For distributed config: directory URI

Notes

Issues

ServiceReference

Property	Description
uri	Unique name of resource and path rooted at service uri
description	JSON Pointer to Resource description (i.e., resourcequiles.json) folder

servicequiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/service/schema#",
  "uri": "http://todo.services.my-company.intra",
  "name": "todo",
  "resources": [
      {
        "uri": "/resources/todo",
        "description": {"$ref": "/resources/todo#"}
      }
    ]
}

Service

Property	Description
$schema	Specifies conforming JSON Schema
uri	For DNS: Rooted path to service "load balancer"
	For distributed config: Unique service name
registry	The location of service registry
name	Unique name of service in registry
resources	List of resources provided by service

Notes

Issues

ResourceReference

Property	Description
uri	Unique name of resource and path rooted at service id
description	JSON Pointer to Resource description (i.e., resourcequiles.json) folder

Notes

1. uri must be unique in the service and matching uri in quiles file.

Issues

resourcequiles.json

Resource

Property	Description
uri	Unique name of resource
	For DNS: rooted at service uri
schema	JSON Schema of resouce
routines	List of routines for resource

Notes

Issues

RoutineReference

Property	Description
uri	The URI of routine and root for relative paths
description	JSON Pointer to Routine description (i.e., routinequiles.json) folder

Notes

1. uri must be unique in the service and matching uri in quiles file.

Issues

routinequiles.json

Routine

Property	Description
$schema	Specifies conforming JSON Schema
uri	The uri of routine and root for relative paths
resource	The resource on which the action is routine is being executed
name	The routine's action name
messages	Lists all messages associated with this routine's conversation

Notes

1. uri must be unique in the service
2. name must be unique for the resource

Issues

1. resource is in the path of the routine uri. Does it function as a back pointer then? Is that the right division? Is it a reasonable convention?
2. What security information is needed?

Message

Property	Description
verbopt	The message's HTTP Message type
action	The message's action
direction	Either to the resource or from the resource
schema	The JSON Schema that defines the action. Includes Hyperschema

Notes

1. action must be unique within routine

Issues

1. action should be should follow a vocabulary. Should there be a canonical set of actions?
2. Is to sufficient to mark a message as an event? Probably not enough information. All subscribers would need to query the resource definition. Sounds very chatty.
3. schema could theoretically be inline. Good or bad? Enforce JSON Pointer? Can you?
4. Can you group a set of supporting routines, for reference id lookups? (Say you want to person id, for example, you would need to look up users.)

Goals

• Self description with HTML
  • Self description static interface (i.e., hyperschema)
  • Self description dynanic interface (i.e., hypermedia)
• REST based
  • Supports HTTP
  • Supports DNS routing
  • Supports embedding REST in WebSockets
  • Supports embedding REST in socket.io for public APIs.
  • Supports destributed configuration manager for routing
  • Supports embedding REST in brokered message queue transport.
• Supports versioning
  • Semver'ed Server Contract
  • Client Contracts
  • Client Driven Server Contracts including Client Unit tests
• Supports scaling
  • Asyncronous
  • Reactive & Actor-based
  • Self scaling
• Polyglot service implementation
• Provides PaaS container abstraction (i.e. "microcontainers")
• Provides explicit abstracted support for
  • destributed configuration management
  • metrics
  • logging
  • error/notification propegation
• Supports explicit abstracted support for security
  • Authentication, Authorization, Accounting
  • Ecryption, Hashing services, etc.
  • Identity Services

01_servicedirectory.md

My Company Services

Directory: http://services.my-company.com

Name	Location	Description
todo	http://todo.services.my-company.com	Provides TODO application services.

01_todoservice.md

My Company todo Service

Service: http://todo.services.my-company.com

Resources

Name	Location	Description
todo	http://todo.services.my-company.com/resources/todo	Provides access to the todo resource.

02_todoresource.md

My Company todo Service todo Resource

Resource: http://todo.services.my-company.com/resources/todo

Messages

Verb	Request	Response	Description
POST	new-todo-request	new-todo-result	Creates a new todo resource.

Routines

Name	Message	Direction	Description
new-todo	new-todo-request	to	Request message for the new-todo routine.

03_newtodoroutine.md

My Company todo Service todo Resource new-todo Routine

03_posttodomessage-resultexample.json

{
  "contract": {
    "url": "//todo.services.my-company.com/resources/todo",
    "consumerId": "ZYX",
    "version": "v1.0.1"
  },
  "data": {
    "_links": {
      "self": { "href": "//todo.services.my-company.com/resources/todo/123" }
    },
    "id": 123,
    "text": "This is a new todo.",
    "status": "active",
    "usrid": "147",
    "impid": null,
    "depid": null,
    "createdate": "2016-03-15T16:23:17.330Z",
    "moddate": "2016-03-15T16:23:17.330Z"
  },
  "messages": [
  ],
  "identity": {
    "tid": "ABC",
    "sid": "DEF",
    "cid": "GHI",
    "mid": "JKL",
    "mtid": "MNO"
  },
  "endpoints": {
    "sender": {
      "scid": "456",
      "dcid": "789"
    },
    "receiver": {
      "scid": "466",
      "dcid": "799"
    }
  },
  "tenant": {
    "tnid": "369",
    "tnoid": "157"
  }
}

03_posttodomessage.md

My Company todo Service todo Resource POST Message

new-todo-request (http://todo.servcies.my-company.com/resources/todo/messages/new-todo-request/schema)

{
  "text": "This is a new todo."
}

[X] Full result [ ] JSON Patch result

[ go ]

new-todo-result (http://todo.servcies.my-company.com/resources/todo/messages/new-todo-result/schema)

{
  "contract": {
    "url": "//todo.services.my-company.com/resources/todo",
    "consumerId": "ZYX",
    "version": "v1.0.1"
  },
  "data": {
    "_links": {
      
    },
    "id": 123,
    "text": "This is a new todo.",
    "status": "active",
    "usrid": 147,
    "impid": null,
    "depid": null,
    "createdate": "2016-03-15T16:23:17.330Z",
    "moddate": "2016-03-15T16:23:17.330Z"
  },
  "messages": [
  ],
  "identity": {
    "tid": "ABC",
    "sid": "DEF",
    "cid": "GHI",
    "mid": "JKL",
    "mtid": "MNO"
  },
  "partitions": {
    "sender": {
      "scid": 456,
      "dcid": 789,
    },
    "receiver": {
      "scid": 456,
      "dcid": 789,
    },
  },
  "tenant": {
    "tnid": 369,
    "tnoid": 157,
  }
}

10_endpointpartition.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Message Endpoint Partition",
  "description": "Quiles message fields supporting service partitioning",
  "type": "object",
  "properties": {
    "scid": {
      "title": "Service Center Id",
      "description": "Id of the service center receiving or sending the message",
      "type": "string"
    },
    "dcid": {
      "title": "Data Center Id",
      "description": "Id of the data center receiving or sending the message",
      "type": "string"
    }
  },
  "required": [ "ssid", "dsid" ]
}

10_messageidentity.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Message Identity",
  "description": "Quiles Message identity fields",
  "properties": {
    "tid": {
      "title": "TransactionId",
      "description": "Globally unique logical business transaction in which this message participates. Can cross multiple services.",
      "type": "string"
    },
    "sid": {
      "title": "SessionId",
      "description": "Unique authenticated session between two Quiles endpoints.",
      "type": "string"
    },
    "cid": {
      "title": "ConversationId",
      "description": "Uniuqe message exchange instance determined by the messages exchange pattern of which this message is a part.",
      "type": "string"
    },
    "mid": {
      "title": "MessageId",
      "description": "Unique Id of the message being sent.",
      "type": "string"
    },
    "mtid": {
      "title": "MessageTransmissionId",
      "description": "Nonce value, unique for every time a message was transmitted in the face of transmission failure.",
      "type": "string"
    }
  },
  "required": ["mid", "mtid"]
}

10_notificationmessage.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Diles Notification Message",
  "description": "A Diles Notification Message",
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "pattern": "[0-9A-Fa-f]{16}"
    },
    "message": {
      "type": "string"      
    },
    "args": {
      "type": "array"
    }
  },
  "required": ["code", "message"]
}

10_servicemessage.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Service Message",
  "description": "A Quiles Service Message",
  "type": "object",
  "properties": {
    "contract": { "$ref": "http://github.com/latticework/diles/schemas/blob/v1.0.0/servicemessagecontract.schema.json/#" },
    "data": { "type": "object" },
    "messages": {
      "type": "array",
      "items": { "$ref": "http://github.com/latticework/diles/schemas/blob/v1.0.0/notificationmessage.schema.json/#" }
    },
    "identity": { "$ref": "http://github.com/latticework/quiles/schemas/blob/v1.0.0/messageidentity.schema.json/#" },
    "partitions": {
      "description": "Message fields supporting partitioning",
      "type": "object",
      "properties": {
        "sender": { "$ref": "http://github.com/latticework/quiles/schemas/blob/v1.0.0/endpointpartition.schema.json/#" },
        "receiver": { "$ref": "http://github.com/latticework/quiles/schemas/blob/v1.0.0/endpointpartition.schema.json/#" }
      },
      "required": [ "sender", "receiver" ]
    },
    "tenent": { "$ref": "http://github.com/latticework/quiles/schemas/blob/v1.0.0/tennentidentity.schema.json/#" }
  },
  "required": [ "contract", "messages", "identity", "tennet" ]
}

10_servicemessagecontract.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Service Message Contract",
  "description": "A Quiles service message contract",
  "type": "object",
  "properties": {
    "url": {
      "description": "The canoncial location of the Quiles service resource",
      "type": "string"
    },
    "consumerId": {
      "description": "The registered identity of the sender. May be an API key, etc.",
      "type": "string"
    },
    "version": {
      "description": "The registered Quiles contract version number for the consumer. Semver format.",
      "type": "string"
    }
  }
}

10_tenantidentity.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Tenant Identity",
  "description": "Tenant identity fields",
  "properties": {
    "tnid": {
      "description": "Identity of the tenant. Can be API Key or other identity field.",
      "type": "string"
    },
    "tnoid": {
      "description": "Identity of the tenant organization associated with a message.",
      "type": "string"
    }
  },
  "required": ["tnid"]
}

11_directoryquiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/directory/schema#",  
  "uri": "http://services.my-company.com",
  "services": [
      {
        "uri": "http://todo.services.my-company.com",
        "description": {"$ref": "http://todo.services.my-company.com#"}
      }
    ]
}

12_servicequiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/service/schema#",
  "uri": "http://todo.services.my-company.com",
  "name": "todo",
  "resources": [
      {
        // need version.
        "uri": "/resources/todo",
        "description": {"$ref": "/resources/todo#"}
      }
    ]
}

13_resourcequiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/service/schema#",
  "uri": "/resources/todo",
  "name": "todo",
  "schema": { "$ref": "/resources/todo#" },
  "version": "v0.1.0",
  "routines": [
    {
      "uri": "/resources/todo/routines/new-todo",
      "description": {"$ref": "/resources/todo/routines/new-todo#"}
    },
    {
      "uri": "/resources/todo/routines/set-todo",
      "description": {"$ref": "/resources/todo/routines/set-todo#"}
    },
    {
      "uri": "/resources/todo/routines/get-todo",
      "description": {"$ref": "/resources/todo/routines/get-todo#"}
    },
    {
      "uri": "/resources/todo/routines/remove-todo",
      "description": {"$ref": "/resources/todo/routines/remove-todo#"}
    }
   ]
}

14_get-todo-request.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "new-todo-request message",
  "description": "Request message for the new-todo routine.",
  "type": "object",
  "properties": {
    // TODO: How do we handle unique resource paths?
    // TODO: How do we handle batching?
    "id": {
      "description": "The unique id of the todo",
      "type": "string",
      "maxLength": 512,
      "minLength": 1
    },
    "responseUrl": {
      "description": "The callback URL",
      "type": "string",
      "pattern": "^[-a-zA-Z0-9@:%_\\+.~#?&//=]{2,256}\\.[a-zA-Z]{2,4}\b(\\/[-a-zA-Z0-9@:%_\\+.~#?&//=]*)?$"
    }
  },
  "required": ["responseUrl"]
}

14_get-todo-result.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "new-todo-request message",
  "description": "Request message for the new-todo routine.",
  "type": "object",
  "allOf": [
      { "$ref": "http://github.com/latticework/quiles-schemas/service-result/#"},
      { "properties": {
          "data": {
            "properties": {
            }
          }
        },
        "required": []
      }
  ],
  "required": ["text"]
}

14_get-todo_routinequiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/routine/schema#",
  "url": "/resources/todo/routines/get-todo",
  "resource": "../..#",
  "name": "get",
  "messages": [
    {
      "verb": "POST",
      "action": "request",
      "direction": "to",
      "schema": {"$ref": "actions/get-todo-request"}
    },
    {
      "verb": "POST",
      "action": "result",
      "direction": "from",
      "schema": {"$ref": "actions/get-todo-result"}
    }
  ],
  "events": [
    {
      
    }
  ]
}

14_new-todo-request.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "new-todo-request message",
  "description": "Request message for the new-todo routine.",
  "type": "object",
  "properties": {
    "text": {
      "description": "The todo entry text",
      "type": "string",
      "maxLength": 512,
      "minLength": 1
    },
    "responseUrl": {
      "description": "The callback URL",
      "type": "string",
      "pattern": "^[-a-zA-Z0-9@:%_\\+.~#?&//=]{2,256}\\.[a-zA-Z]{2,4}\b(\\/[-a-zA-Z0-9@:%_\\+.~#?&//=]*)?$"
    }
  },
  "required": ["text", "responseUrl"]
}

14_new-todo-result.schema.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "new-todo-request message",
  "description": "Request message for the new-todo routine.",
  "type": "object",
  "allOf": [
      { "$ref": "http://github.com/latticework/quiles-schemas/service-result/#"},
      {
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": { "$ref": "../../#" }
            }
          }
        } 
      }
  ]
}

14_new-todo_routinequiles.json

{
  "$schema": "http://quiles.io/schemas/v0.0.1/routine/schema#",
  "url": "/resources/todo/routines/new-todo",
  "resource": "/resources/todo",
  "name": "new",
  "messages": [
    {
      "verb": "POST",
      "action": "request",
      "direction": "to",
      "schema": {"$ref": "/actions/new-todo-request"}
    },
    {
      "verb": "POST",
      "action": "result",
      "direction": "from",
      "schema": {"$ref": "/actions/new-todo-result"}
    }
  ],
  "events": [
      {
        
      }
    ]
}