APIM 3.0 Services support encapsulation and reuse. A Service and all of its versions live in a specific project folder. We recommend that you also create related resources, such as tasks, accounts, and pipelines, in the Service version assets folder.

This encapsulation controls usage and ensures that the correct Policies are always applied to requests to those endpoints.

Specifications

You can create a Service in APIM 3.0 from an OAS specification 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 specifications.

To create a Service from scratch, you manually add native (tasks) or external endpoints and define their paths and methods. From that definition, APIM 3.0 creates a OAS 3.x specification that Service consumers can view in the 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 at the Service, endpoint path and method levels. For each Service, you can add documentation that displays after you publish the Service in the DeveloperHub. Documentation can include text and images.

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 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.

Wrap 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. Click the error or warning icon to view the log. From the log, click a message to navigate to the referenced location. The following image shows the validation icons for an example convert endpoint:

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, and the supported HTTP methods for retrieving, updating, or deleting a user:

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.

The following describe how to perform tasks related to Services and endpoints:

• Create a Service
• Add a native endpoint
• Add an external endpoint
• Add documentation
• Test a Service