Skip to main content
Previous section   Next section

Accessing the Public Service Registry through the Public REST API

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:

  • Return information about all services to all users, including those logged in anonymously. With this policy, getting information about a service does not imply that you have permissions to call the service.

  • Limit the services returned to the ones that the user has permission to call based on the login account or anonymous access.

Each service registry entry contains the following information:

  • Service identification, which consists of a name, a domain, and a version.

  • Endpoint URL, which gives the address to call the service. Typically, this address is on the ESB server. The endpoint of the external server that actually performs the service is not returned.

  • Protocol used to call the service, such as REST, SOAP, HTTP, or TCP.

  • Return mechanism used by the service, such as synchronous return or callback.

  • Description, which provides a brief text summarizing the service.

  • Topics, which are used to search for services.

  • Schema, which contains a schema description of the return messages for those messages that have a schema language. Schema information includes the schema format, provide a URL for the schema defintion, or provide the content of the schema.

  • Actions describe the HTTP request methods that can be used at the specified endpoint. Each action can describe the impact of the request method on the server and can specify the schema of the incoming message and response message.

  • Contacts describe users or organizations that can provide information or support for the service.

  • Attributes provide a mechanism for the registry administrator to extend the information provided about each service. Attributes consist of a series of name-value pairs.

  • Files provide a mechanism to provide any set of files for the service. Typically, these are used to provide documentation or templates for using the service. When the public API returns information about a file, it does not include the file contents because the contents can be very large. To access the file contents, you must make an explicit request.

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
GET /services/id/name/domain/version/file/filename
Returns the specified file.
Get Services
GET /services
Shows all services accessible to the user.
Get Services By ID
GET /services/id/name/domain/version
Returns the service, if accessible to the user, that matches the specified name, domain, and version.
Get Services By Protocols
GET /services/protocols/protocol-list
Shows all services accessible to the user that match a protocol in the list.
Get Services By Stages
GET /services/stages/stage-list
Shows all services accessible to the user that match a stage in the list.
Get Services By Version
GET /services/version/version
Shows all services accessible to the user that match the specified version.
Get Services By Word
GET /services/includesword/search-text
Shows all services accessible to the user that match the specified search text.
Get Services Since Modified
GET /services/modifiedsince/date-time
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
       }
    ]
}
]
Copy code to clipboard

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:

  • Identity—Specifies the name or other identity of the person or organization.

  • Type—Specifies whether the contact is the service Author, Consumer, Provider, Operator, Manager, or Sponsor.

  • Details—Specifies details about the contact.

  • Business Partner—A field that is used internally by the service registry but that is not useful to an application using the public API.

  • Notes—Specifies supplementary information about the contact.

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:

  • Type—Specifies the name of the schema definition mechanism used to describe the schema. It can bee WSDL, XSD, HL7, SEF, X12, AST, EDF, or a custom schema definition mechanism.

  • Ref—Specifies the URL of the schema definition.

  • Content—Provides the full text content of the schema definition.

  • Notes—Provides supplementary information about the schema.

  • Thumbnail—Provides a brief excerpt from the schema.

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:

  • Filename—Provides the name of the file. Typically, this includes the file extension. You cannot have two files in a single registry entry that have the same filename.

  • File Extension—Provides information on the format and purpose of the file. Optional.

  • MIMEType—Provides information on the application used to access the file. Optional.

  • CharEncoding—Provides the character encoding information. Optional.

  • File Size—Provides the file size. Optional.

  • Contents—This field is always null in the JSON service description. You must call the Get File By ID call to get the file contents.

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:

  • Name—Specifies the name used by the Registry to identify this action.

  • Ref—Specifies a string identifier of the action.

  • Verb—Specifies the HTTP request method. Typically, this is GET, PUT, POST, or DELETE, but it can be any HTTP request method.

  • Description—Specifies a text explanation of the action.

  • Request Schema—Specifies the format of the incoming message body and consists of the following subfields: Type, Ref, Notes, Thumbnail, and Content.

  • Response Schema—Specifies the format of the response message body and consists of the following subfields: Type, Ref, Notes, Thumbnail, and Content.

  • Read Only—If checked, specifies that the call does not make any changes to the state of the server.

  • Idempotent—If checked, specifies that making multiple identical calls have the same impact on the server as making a single call.

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:

  • Protocol—selects any service that has a protocol in the list. Protocols can be any of the following: File, FTP, HL7, HTTP, REST, SOAP, SQL, X12, and any custom value.

  • Stage—selects any service that has a stage that is specified in the list. Stages can be any of the following: Concept, Development, Test, Staging, Live, Deprecated, and Defunct.

  • Version—selects any service that has the specified version.

  • Text search—selects any service that contains the specified text in any of the following fields: Name, Domain, Description, Endpoint, and Topics. The text comparison is not case-sensitive.

  • Modification date—selects any service whose entry has been modified after the specified date.

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:

  • Name

  • Domain

  • Description

  • Endpoint

  • Topics

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.