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.
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": "2022-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://mymachine.mynetwork.com:57774/csp/registry/docserver/public",
"ResponseStyle": "Sync",
"LastModified": "2022-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 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 specifies the category of the service.
Version identifies the version of the service.
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.
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 provides a brief explanation of the service
Endpoint specifies the location of the service. This is the location you use to call the service.
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.
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 provide a series of terms that are useful in searching for services using the Get Services By Word call.
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.
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.
Always has a true value. Used internally in the service registry.
Attributes specify a list of Name-Value pairs that allow an ESB service registry to contain any information about a service.
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 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.
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
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.