Purpose and Scope

Provision Service provides applications and other services (henceforth "consumers") with (1) unique identifiers within the nGen Platform and (2) a list of other services available for consumption.

We recommend all consumers bootstrap themselves by calling the Provision Service. This bootstrap sequence identifies and connects them within the nGen Platform. After bootstrap, the consumer needs no further contact with the Provision Service.

Terminology

Provision Service uses the following terminology:

• Consumer - any application or service interacting with the nGen Platform.
• BSG RA GUID- aka BSG Reference Architecture Globally Unique Identifier. A unique string that identifies each consumer. BSG RA GUIDs have the form: 6b0c73c0-bsga-kali-rome-001b7744e04a. In the Ruby language you can produce a similarly formatted identifier using the UUIDTOOLS library command: UUID.timestamp_create().to_s.
• Provision- the catalog of nGen Platform services available to an individual consumer. The Provision names and locates the service.

Conventions and Return Codes

The API supports the nGen Platform conventions:

• Bad Request failures (e.g. supplying the wrong input parameters) returns HTTP code 400
• Authorization failures (e.g. using unknown user credentials) returns HTTP code 401
• Item Not Found failures (e.g. supplying an id for missing data) returns HTTP code 404
• Unsupported Service Invocations (e.g. using unsupported verbs) returns HTTP code 405
• Not Acceptable (e.g. requesting an unsupported format - .xml/.html/etc) returns HTTP code 406
• Internal Errors and other exceptions returns HTTP code 500
• As a general guideline, nGen Platforms services return appropriate HTTP codes wherever possible.

API

• GET /bsgra_guids.html or GET /provisions.html
  This documentation screen.
• POST /bsgra_guids.xml
  Create a new BSG RA GUID for the given consumer instance. See above for the format.
  • Bad Request: 400, in the event an BSG RA GUID already exists for this consumer instance.
  • Created: 201. The expected XML request body:

    <?xml version="1.0" encoding="UTF-8"?>
    <hash>
      <name>kalivo</name>
      <instance>spud</instance>
    </hash>

    Expected return value, retrieved using XPATH (//bsgra_guid):

    <?xml version="1.0" encoding="UTF-8"?>
    <bsgra_guids>
      <bsgra_guid_entry>
        <bsgra_guid>76404890-a8df-11dc-8979-0019b9788705</bsgra_guid>
        <name>kalivo</name>
        <instance>spud</instance>
      </bsgra_guid_entry>
    <bsgra_guids>

• POST /bsgra_guids.json
  Create a new BSG RA GUID for the given consumer instance. See above for the format.
  • Bad Request: 400, in the event an BSG RA GUID already exists for this consumer instance.
  • Created: 201. The expected XML request body:

    <?xml version="1.0" encoding="UTF-8"?>
    <hash>
      <name>kalivo</name>
      <instance>spud</instance>
    </hash>

    Expected return value:

    {
      "bsgra_guid": "76404890-a8df-11dc-8979-0019b9788705",
      "name": "kalivo",
      "instance": "spud"
    }

• GET /bsgra_guids/<consumer_name>.xml?instance=<instance>
  Returns the BSG RA GUID matching this consumer instance.
  • Success: 200. The returned XML response body is below, the BSG RA GUID can be retrieved using XPATH (//bsgra_guid):

    <?xml version="1.0" encoding="UTF-8"?>
    <bsgra_guids>
      <bsgra_guid_entry>
        <bsgra_guid>6b0c73c0-bsga-kali-rome-001b7744e04a</bsgra_guid>
        <name>kalivo</name>
        <instance>rome</instance>
      </bsgra_guid_entry>
    <bsgra_guids>

• GET /bsgra_guids/<consumer_name>.json?instance=<instance>
  Returns the BSG RA GUID matching this consumer instance.
  • Success: 200. The returned JSON response body is below:

    [{
      "bsgra_guid": "6b0c73c0-bsga-kali-rome-001b7744e04a",
      "name": "kalivo",
      "instance": "rome"
    }]

• GET /bsgra_guids.xml
  Returns the all BSG RA GUIDs.
  • Success: 200. The returned XML response body is below:

    <?xml version="1.0" encoding="UTF-8"?>
    <bsgra_guids>
      <bsgra_guid_entry>
        <bsgra_guid>6b0c73c0-bsga-kali-kali-001b7744e04a</bsgra_guid>
        <name>kalivo</name>
        <instance>kalivo</instance>
      </bsgra_guid_entry>
    <bsgra_guid_entry>
        <bsgra_guid>6b0c73c0-bsga-kali-rome-001b7744e04a</bsgra_guid>
        <name>kalivo</name>
        <instance>rome</instance>
      </bsgra_guid_entry>
    <bsgra_guids>

• GET /bsgra_guids.json
  Returns the all BSG RA GUIDs.
  • Success: 200. The returned JSON response body is below:

    [{
      "bsgra_guid": "6b0c73c0-bsga-kali-kali-001b7744e04a",
      "name": "kalivo",
      "instance": "kalivo"
    }, {
      "bsgra_guid": "6b0c73c0-bsga-kali-rome-001b7744e04a",
      "name": "kalivo",
      "instance": "rome"
    }]

• GET /provisions/<bsgra_guid>.xml
  Returns the provisions assigned the consumer instance with the corresponding BSG RA GUID.
  Supports request parameters:
  digest - A digest of the concatenated provision name/endpoint_uri ordered by name and ordering.
  • Not Modified: 304. The digest matches the current digest of provisions
  • Success: 200. The returned XML response body is below, the list of provisions can be retrieved using XPATH (//provisions/provision):

    <?xml version="1.0" encoding="UTF-8"?>c <provisions>
      <provision>
        <created_at type="datetime">2007-11-20T15:25:53-06:00</created_at>
        <endpoint_uri>http://provisiontest.bsgplatform.com/provisions</endpoint_uri>
        <name>service_provision</name>
        <ordering type="integer">1</ordering>
        <updated_at type="datetime">2007-11-20T15:25:53-06:00</updated_at>
      </provision>
      <provision>
        <created_at type="datetime">2007-11-20T15:25:54-06:00</created_at>
        <endpoint_uri>http://provisiontest.bsgplatform.com/bsgra_guids</endpoint_uri>
        <name>service_provision_bsgra_guids</name>
        <ordering type="integer">1</ordering>
        <updated_at type="datetime">2007-11-20T15:25:54-06:00</updated_at>
      </provision>
    </provisions>

• GET /provisions/<bsgra_guid>.json
  Returns the provisions assigned the consumer instance with the corresponding BSG RA GUID.
  Supports request parameters:
  digest - A digest of the concatenated provision name/endpoint_uri ordered by name and ordering.
  • Not Modified: 304. The digest matches the current digest of provisions
  • Success: 200. The returned JSON response body is below):

    [{
      "created_at": "2007/11/20 15:25:53 -0600"
      "endpoint_uri": "http://provisiontest.bsgplatform.com/provisions"
      "name": "service_provision"
      "ordering": 1
      "updated_at": "2007/11/20 15:25:53 -0600"
    }, {
      "created_at": "2007/11/20 15:25:54 -0600"
      "endpoint_uri": "http://provisiontest.bsgplatform.com/bsgra_guids"
      "name": "service_provision_bsgra_guids"
      "ordering": 1
      "updated_at": "2007/11/20 15:25:54 -0600"
    }]

• GET /provisions.xml?name=<service_name>
  Returns the provisions with the corresponding service name.
  Supports request parameters:
  name - The name of the service to return.
  • Success: 200. The returned XML response body is below, the list of provisions can be retrieved using XPATH (//provisions/provision):

    <?xml version="1.0" encoding="UTF-8"?>c <provisions>
      <provision>
        <bsgra_guid>6b0c73c0-bsga-kali-kali-001b7744e04a</bsgra_guid>
        <created_at type="datetime">2007-11-20T15:25:53-06:00</created_at>
        <endpoint_uri>http://provisiontest.bsgplatform.com/provisions</endpoint_uri>
        <name>service_provision</name>
        <ordering type="integer">1</ordering>
        <updated_at type="datetime">2007-11-20T15:25:53-06:00</updated_at>
      </provision>
      <provision>
        <bsgra_guid>6b0c73c0-bsga-kali-rome-001b7744e04a</bsgra_guid>
        <created_at type="datetime">2007-11-20T15:25:54-06:00</created_at>
        <endpoint_uri>http://provisiontest.bsgplatform.com/bsgra_guids</endpoint_uri>
        <name>service_provision_bsgra_guids</name>
        <ordering type="integer">1</ordering>
        <updated_at type="datetime">2007-11-20T15:25:54-06:00</updated_at>
      </provision>
    </provisions>

• GET /provisions.json?name=<service_name>
  Returns the provisions with the corresponding service name.
  Supports request parameters:
  name - The name of the service to return.
  • Success: 200. The returned JSON response body is below):

    [{
      "bsgra_guid": "6b0c73c0-bsga-kali-kali-001b7744e04a"
      "created_at": "2007/11/20 15:25:53 -0600"
      "endpoint_uri": "http://provisiontest.bsgplatform.com/provisions"
      "name": "service_provision"
      "ordering": 1
      "updated_at": "2007/11/20 15:25:53 -0600"
    }, {
      "bsgra_guid": "6b0c73c0-bsga-kali-rome-001b7744e04a"
      "created_at": "2007/11/20 15:25:54 -0600"
      "endpoint_uri": "http://provisiontest.bsgplatform.com/bsgra_guids"
      "name": "service_provision_bsgra_guids"
      "ordering": 1
      "updated_at": "2007/11/20 15:25:54 -0600"
    }]

• POST /provisions/<bsgra_guid>.xml
  Create a new Provision for the specified BSG RA GUID.
  • Bad Request: 400, in the event an BSG RA GUID already exists for this consumer instance.
  • Created: 201. The expected XML request body::

    <?xml version="1.0" encoding="UTF-8"?>
    <provision>
      <name>test_service</name>
      <endpoint_uri>http://testservice.ngenplatform.com</endpoint_uri>
    </provision>

    Expected return value, retrieved using XPATH (/provision):

    <?xml version="1.0" encoding="UTF-8"?>
    <provision>
      <created_at type="datetime">2007-11-20T15:25:54-06:00</created_at>
      <endpoint_uri>http://testservice.ngenplatform.com</endpoint_uri>
      <name>test_service</name>
      <ordering type="integer">1</ordering>
      <updated_at type="datetime">2007-11-20T15:25:54-06:00</updated_at>
    </provision>
    

• POST /provisions/<bsgra_guid>.json
  Create a new Provision for the specified BSG RA GUID.
  • Bad Request: 400, in the event an BSG RA GUID already exists for this consumer instance.
  • Created: 201. The expected request body should be "application/x-www-form-urlencoded" with the following:
    • provision[name] - The name of the provision to create
    • provision[endpoint_uri] - The endpoint of the provisiont o create
    Expected return value:

    {
      "created_at": "2007/11/20 15:25:53 -0600"
      "endpoint_uri": "http://testservice.ngenplatform.com"
      "name": "test_service"
      "ordering": 1
      "updated_at": "2007/11/20 15:25:53 -0600"
    }

• DELETE /provisions/<bsgra_guid>/<service_name>/<Base64 encoded endpoint_uri>
  Delete the specified Provision for the specified BSG RA GUID. Deletes the provision with matching, service name and endpoint. If any provision is lower priority for same BSG RA GUID and service, its ordering will be automatically increased.
  NOTE: The endpoint MUST be Base64 encoded.
  • Bad Request: 400, if endpoint is not encoded properly or service_name or bsgra_guid not provided
  • Not Found: 404, if matching provision is not found
  • Success: 200.

Gadgets

The provision service all contains the following gadgets:

• /gadgets/display_provisions - Displays admin screen to view/create BSG RA GUIDS and their respective provisions

© Copyright 2006-8 nGenera Corporation - All rights reserved. Version 3.3.0GA