Using Ensemble as an ESB
Accessing the Public Service Registry through the Public REST API
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The public REST API provides read access to the public Service Registry. The API provides information about the services available through the ESB. You can make REST calls to return information about all services or can query for services that meet specified conditions. The calls return service information in JSON.

Depending on how the ESB is configured, you can access the API by with a username and password or by anonymous access. The registry returns services based on the permissions given to the user or to anonymous access. The service registry administrator controls which services are returned depending on the login information. For example, the administrator may choose to configure the registry in one of the following ways:
Each service registry entry contains the following information:
The following sections describe:
Summary of the Service Registry Public API
This section provides a summary of the REST calls in the public API. Full details about each call are provided in Service Registry Public API Reference.
REST Call URL and Description
Get About
GET /about
Lists the public API REST calls that are available.
Get File By ID
Returns the specified file.
Get Services
Shows all services accessible to the user.
Get Services By ID
Returns the service, if accessible to the user, that matches the specified name, domain, and version.
Get Services By Protocols
Shows all services accessible to the user that match a protocol in the list.
Get Services By Stages
Shows all services accessible to the user that match a stage in the list.
Get Services By Version
Shows all services accessible to the user that match the specified version.
Get Services By Word
Shows all services accessible to the user that match the specified search text.
Get Services Since Modified
Shows all services accessible to the user whose registry entry has been created or updated since the specified date-time.
JSON Description of Services
The Get Services calls return a JSON message with any number of services. If no services match the Get Services request and are accessible to the user, the call returns an empty JSON message. Otherwise, the Get Services call returns a JSON message with one or more services that match the request and are accessible to the user. This section provides an example of a returned JSON message and describes the fields in the message.
The following message could be returned by any Get Services call. The WSDL schema is abbreviated in the listing but appears in full in the JSON message.
[
{
    "Name": "MathServiceSOAP",
    "Domain": "UnitTest",
    "Version": "1.1",
    "Stage": "Live",
    "Protocol": "SOAP",
    "Description": "Add 2 Numbers",
    "Endpoint": "https://jgm6457/enslatest/csp/support/Demo.SOAP.MathService.cls",
    "ResponseStyle": "Sync",
    "LastModified": "2015-03-16 19:07:47.469",
    "Topics": 
    [
        "Test",
        "Maths"
    ],
    "Contacts":
    [
      {
        "Identity": "QD Developer Moon",
        "Type": "Operator",
        "Details": "Details of contact",
        "BusinessPartner": "QD",
        "Notes": "This SOAP service is designed to have minimum moving parts"
      }
    ],
    "Schema":
    {
       "Type": "Notes",
       "Ref": "https://jgm6457/enslatest/csp/support/Demo.SOAP.MathService.cls?wsdl=1",
       "Content": "<definitions targetNamespace='http://tempuri.org'> ...</definitions>",
       "Notes": "Some WSDL"
    },
    "Public": true,
    "Attributes":
    [
       {
          "Name": "One",
          "Value": "1"
        }
    ],
    "Files":
    [
       {
          "Filename": "SOAPMathService.WSDL",
          "FileExtention": ".WSDL",
          "MIMEType": "text/text",
          "CharEncoding": "UTF-8",
          "FileSize": "1.44 KB",
          "Contents": null
       }
    ],
    "Actions":
    [
       {
          "Name": "Sum",
          "Ref": "Sum",
          "Verb": "POST",
          "Description": "Add up 2 numbers",
          "ReadOnly": false,
          "Idempotent": true
       }
    ]
},
{
    "Name": "PublicREST",
    "Domain": "UnitTest",
    "Version": "0.9",
    "Stage": "Live",
    "Protocol": "REST",
    "Description": "REST Call for the Public Registry",
    "Endpoint": "http://jgm527clone.iscinternal.com:57774/csp/registry/docserver/public",
    "ResponseStyle": "Sync",
    "LastModified": "2015-03-05 16:15:33.38",
    "Topics": 
    [
       "Public",
       "Search",
    ],
    "Public": true,
    "Attributes":
    [
       {
          "Name": "Security",
          "Value": "Username and Password"
       }
    ],
    "Files":
    [
       {
           "Filename": "TestPlan",
           "MIMEType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
           "CharEncoding": "UTF-8",
           "FileSize": "16.95 KB",
            "Contents": null
       }
    ],
    "Actions":
    [
       {
          "Name": "public",
          "Ref": "public",
          "Verb": "GET",
          "Description": "Returns REST endpoint for public registry",
          "RequestSchema": 
          {
              "Type": "Notes",
              "Notes": "This is the REST endpoint to query the public Registry"
          },
          "ResponseSchema":
          {
             "Type": "REST Information
          },
          "ReadOnly": true,
          "Idempotent": true
       }
    ]
}
]
The following lists and describes the fields that can appear in the service description. For all fields, the ESB site may provide guidelines and general practices, that provide information on how the fields are used in its service registry.
Name
Name identifies the service. The other attributes identifying the service are the Domain and Version. The Domain typically identifies the category of the service and Version is a string representing a version number. The combination of Name, Domain, and Version is unique for each service registry entry. For example, two or more services may have the same name as long as the domains are different or the versions are different.
Domain
Domain specifies the category of the service.
Version
Version identifies the version of the service.
Stage
Lifecycle Stage describes the development state of the service. It can have one of the following values: Concept, Development, Test, Staging, Live, Deprecated, and Defunct.
Protocol
Service Protocol describes the protocol used by the client to access the service. It can have any of the following values: File, FTP, HL7, HTTP, REST, SOAP, SQL, X12, and any custom value.
Description
Description provides a brief explanation of the service
Endpoint
Endpoint specifies the location of the service. This is the location you use to call the service.
Response Style
Response Style describes how the service returns a value. It may have one of the following values: Sync, Callback, Remote Deposit, or a blank value.
Last Modified
The date and time that the registry entry was last changed in the ESB registry. you can discover services that were added or updated since a specified date and time by calling Get Services By Modified.
Topics
Topics provide a series of terms that are useful in searching for services using the Get Services By Word call.
Contacts
Contacts specify people or organizations that support or are associated with the service. A contact can contain the following subfields:
Schema
The Schema describes the structure of the service messages. Schema contains subfields that describe or contain the structure definition. Schema can contain the following subfields:
Public
Always has a true value. Used internally in the service registry.
Attributes
Attributes specify a list of Name-Value pairs that allow an ESB service registry to contain any information about a service.
Files
Files provide a way to include one or more files in a registry entry. For example, a file can contain documentation on the service. Each file in a single registry entry must have a unique filename. When you make a Get Services call, the returned JSON message does not include the file contents. To get the file contents, you make a separate GetFileByID call. Each File element consists of the following subfields:
Actions
Actions specify the SOAP actions or the REST HTTP request methods that you can use with the specified URL. SOAP actions provide a summary of the information defined in the WSDL. An action can contain the following subfields:
Get All Services
The Get Services REST call returns all service registry entries that you have permission to view. The call returns the complete registry entry for each service except that file contents are omitted. The registry returns all services that you have permission to view. The URL for this call is:
GET /services
For example, a complete URL, including the server and top-level directory is:
https://esb.example.com/registry/services
Get Service by ID
The Get Service by ID call returns information about the identified service. A service is uniquely identified by a name, domain, and version. The URL syntax for this call is:
GET /services/id/name/domain/version
For example, to get the service with the name coffeemaker, the domain demo, and the version 1.0, use the following call:
https://esb.example.com/registry/services/id/coffeemaker/demo/1.0
The Get Service by ID returns the same information for the specified service as is returned for that service by Get All Services. Consequently, if you have called Get All Services, there is no need to call Get Service by ID.
Note:
Although the purpose of this call is to return a single service, you can specify wildcards in the name, domain, and version parts of the URL. If you do use wildcards, the call returns all services that match the specification.
Getting Selected Services
Instead of getting all the services from the registry or getting a single service by ID, you can select a subset of services. You can specify any one the following selection criteria:
The Get Services By Protocols call selects the services that have a protocol that matches one of the ones in the list. The URL syntax for this call is:
GET /services/protocols/protocol-list
The following call returns all services with the REST protocol:
https://esb.example.com/registry/services/protocols/REST
The following call returns all services with either the REST or SOAP protocol:
https://esb.example.com/registry/services/protocols/REST,SOAP
The Get Services By Stages call selects the services that have a stage that matches one of the stages in the list. The URL syntax for this call is:
GET /services/stages/stage-list
The following call returns all services with the Live stage:
https://esb.example.com/registry/services/stages/Live
The Get Services By Version call selects the services that have a version that matches the specified version. The URL syntax for this call is:
GET /services/version/version
For example, the following call returns all services with version 1.0:
https://esb.example.com/registry/services/version/1.0
The Get Services By Word call finds all services that contain the specified search text in any of the following fields:
The URL syntax for the Get Services By Word call is:
GET /services/includesword/search-text
For example, the following call returns all services that have the text string “accounts, payable” in one of the fields:
https://esb.example.com/registry/services/includesword/accounts,%20payable
The Get Services Since Modified call returns all services whose registry entry has been modified after the specific date-time. The URL syntax for this call is:
GET /services/modifiedsince/date-time
For example, the following call returns all services whose entries were modified after the specific date-time:
https://esb.example.com/registry/services/modifiedsince/2015-02-1%2011:30
The date is specified as year-month-day, the URL space code %20 as a separator, and hours:minutes using a 24 hour clock.
Getting File Contents
The Get File By ID call returns the contents of the specified file. It can return either a text or a binary file. It does not return a JSON message or any file metadata, it only returns the contents of the file. The URL syntax for this call is:
GET /services/id/name/domain/version/file/filename
where name/domain/version identify the service and filename specifies the name of the file in that service.
For example, the following call returns the contents of a file:
https://esb.example.com/registry/services/id/coffeemaker/demo/1.0/file/HowToCallCoffeemaker.docx
Note:
You should not use any wildcards in the Get File By ID call. Although it is possible to specify wild cards in the name/domain/version parts of the URL, the behavior of this call is undefined if there are multiple services that match the specification.