Introduction to Services

APIM 3.0 Services support encapsulation and reuse. To keep related assets organized, save all items a Service uses—such as tasks, accounts, and pipelines—in the same project folder where you plan to create the Service. You should also store Service-specific and endpoint-specific Policies in the same location. This structure helps enforce proper usage and reuse of tasks and Policies.

You can create a Service in APIM 3.0 from a Swagger 2.0 specification, an OpenAPI Specification (OAS), or from scratch. We recommend creating Services from specifications because it promotes holistic design that considers business requirements and results in consistent interfaces that are easy for consumers to use. You can use a tool such as the Swagger Editor to create your own specifications.

To create a Service from scratch, you manually add native (tasks) or external endpoints and define their paths and methods. When you publish the Service, APIM 3.0 generates a OAS 3.x specification that Service consumers can view or download in DeveloperHub.

Conceptually, a Service is a container for one or more versions. You can't create a Service without specifying the version and any actions you take, such as editing, testing, or publishing, apply only to one version. If you change the Service name or URL slug, the changes apply to all versions.

Clearly documenting the purpose of a Service and how to use it enables consumers to use it properly and avoid errors. APIM 3.0 provides fields to add descriptions for Services, versions, endpoint paths, methods, and parameters. Content that you add on the Documentation tab displays after you publish the Service in DeveloperHub.This documentation can include text and images.

Specifications

OAS 3.x defines a standard interface to HTTP endpoints so that humans and computers can discover service capabilities without access to the source code. An OAS specification in YAML or JSON format defines the following characteristics:

Endpoint paths (URLs)
Supported HTTP methods
Query, path, and request parameters
Response data and status codes
The structure of data

The following shows an APIM 3.0 Service created from the sample Swagger Pet Store specification:

Service endpoint URLs

Endpoint URLs are an important part of Service discovery. Logical, consistent URLs make it easier for consumers to understand the Service purpose and functionality. A SnapLogic Service endpoint has the following form:

https://hostname/gateway/URL-slug/version/endpoint-paths/

URL components include:

Hostname: The root address. For an endpoint executing on a Cloudplex, a hostname of: https://snaplogic.io. For an endpoint executing on a Groundplex, your hostname or IP address.
URL-slug: A unique value that identifies the Service. For example: MyService
Version: The user-specified version. For example: v1.
Resource Path: One or more paths defined for the endpoint. For example: users.

All endpoints in a Service version use the same URL Slug and version. The endpoint-paths value comes from its Path configuration. A Service can have multiple endpoints each endpoint can have multiple paths (routes), and each path can have support multiple HTTP methods. You can route requests to a specific path by specifying a rule or with an expression. Refer to Service configuration and Endpoint configuration for more information.

Designing pipelines for native endpoints

Service endpoints can support multiple HTTP methods. For example, one endpoint can support create, fetch, update, and delete. To support this in one pipeline, use a Router Snap to execute the correct operation depending on the method and parameters. To use existing pipelines that only support one method, such as create, invoke them as child pipelines. Create a parent pipeline using the Router Snap and use Pipeline Execute Snaps to invoke the child pipelines. Create a task that triggers the parent pipeline, and associate the Service endpoint with that task.

Wrapping legacy SOAP APIs in a Service

Modernization is a common use case for Services. For example, an organization might have legacy SOAP interfaces that would be too costly to update. If you check the REST to SOAP option for an endpoint, APIM 3.0 accepts REST requests from the client, translates them to SOAP for the endpoint, receives the SOAP response, and translates it to JSON for the client. The Service exposes a consistent RESTful interface to clients, who are unaware of the backend implementation.

Validation

Validation runs each time you save a Service component. APIM 3.0 generates errors and warnings. Icons display below the Service tabs as shown below. Click the error or warning icon to view the log. From the log, click a message to navigate to the referenced location.

You can test Services with errors, but you must fix them before publishing. For example:

A valid Server (Snaplex) must be set either for the Service version or for each route (path).
Endpoints with the same name must have different advanced routing rules to distinguish between them.
A Service must have at least one endpoint.
An endpoint must have a Path and at least one HTTP method defined.
Missing response code and description for HTTP method.

You can publish a Service with warnings, but they can indicate things you should address. For example:

No descriptions provided.
No request body or schema provided.
No response body or schema provided.
The Server (Snaplex) differs from the one selected in the Ultra Task.

Example Service from a specification

When you start from a specification, APIM 3.0 creates endpoints and the supported method definitions for you. For example, a Service created from the OAS Pet Store specification has sixteen endpoints. Each endpoint path must be unique in the service. The following shows the user endpoint, with its paths:

By clicking edit, you can view the supported methods for the path:

With this example Pet Store Service, you could implement the functionality with SnapLogic pipelines. The Service endpoints encapsulate functional requirements, such as the ability to create, retrieve, update, and delete users. After completing the appropriate pipelines and tasks, you would map each endpoint to the appropriate Triggered or Ultra Task. Alternatively, you can associate an endpoint with an external service. For example, a public database that lists dog breeds.