Web services are the core building block used to model real-world APIs and websites.

Using web services, you can:


API monitoring and health metrics

Sections

Importing a web service

There are three ways to create a new web service:

  1. Importing a URL
  2. Importing a Swagger / OpenAPI definition
  3. Importing a Postman Collection

Importing a URL

The most simple and minimal way to create a web service is to import a URL. To create a new web service from URL, navigate to the new service page, and input your URL into the Enter a URL field.

  • To preview the import, click Import URL.
  • To finalize the import, click Create service and tests.

Fig 1.1 Import API Spec

Importing a Swagger spec

If you have a formal specification for your web service, like a Swagger definition or OpenAPI Spec, you can import your entire web service configuration and create tests for every documented endpoint. Incredible!

To import your web service from a Swagger spec, visit the New Service page in your Assertible dashboard. From there, click or import a Swagger Spec. You can import your API definition via a URL or file in JSON or YAML format.


Assertible import from GitHub API Swagger spec dry run

Note! If your API spec is in a format that is not Swagger, try using https://apimatic.io/transformer

When you import a Swagger definition, Assertible automatically identifies several critical pieces of information define your web service. Specifically, Assertible:

Importing a Postman Collection

If you use a Postman Collection for testing your web service, you can import the entire configuration and automatically create Assertible tests for each collection item.

To import your web service from a Postman Collection, visit the New Service page in the Assertible dashboard. From there, click or import a Postman Collection. You can import your Postman Collection via a URL or file in JSON format.


Assertible import from Twitter API Postman Collection dry run

Heads up! If your Postman Collection is version 1 format. Import the collection into Postman and export as a version 2 collection.

Note! If your API definition is in a format that is not Postman Collection, try using https://apimatic.io/transformer

How it works:

  • Assertible scans your collection for the primary API host

    If your collections makes HTTP requests to a single URL, Assertible will use that as the API host.

    If your collections makes API calls to multiple APIs, the one with the most items will be used as the API host.

    For best results, it's usually best to have a collection that is geared at defining and testing endpoints for a single API.

    If you use a parameterized base URL (list {{HOST}} or api.{{my-host}}.com, Assertible will not be able to import it without a global variable defining the initial host to use.

  • Assertible creates an API and a test for each item

    If any part of the host URL is a variable, Assertible will not be able to import

    extracted fields:

    • HTTP method
    • HTTP scheme/protocol
    • Test name
    • Descriptions
    • Variables
    • Headers
    • Query parameters
    • Request body
  • All authentications entries are extracted

    If an Auth entry is only used on a single request, Assertible will only add that to the specific test extracted for that entry.

Unsupported features:

  • oauth2
  • environment variables
  • pre-request http requests to populate variables
  • unresolvable {{host}} or {{port}}
  • multipart/formdata and file uploads
  • WebDAV HTTP methods - COPY, LINK, UNLINK, PURGE, LOCK, UNLOCK, PROPFIND, and VIEW are unsupported

Limited support:

  • oauth1
  • oauth2
  • request body

For many of these we are planning to implement enhancements. Reach out to use if you have any feature requests, suggestions, or problems importing your collection

Configuring a web service

A web service can be configured on the dashboard Settings tab.

Assertible dashboard web service settings

There are several fields you can customize:

Name

The name of the web service. Usually this is something as simple as "Assertible API". If API settings are imported from a Swagger specification, the name (and most other settings) will be created automatically.

Host URL

The web service Host URL is the default base URL where your API lives.Generally, the default API host is configured to be the production URL of your web service.

Environments are used to model other deployments URLs for the same web service such as staging, qa, or dev. When you create a web service, a default environment is created named production.

For example, in https://api.assertible.com/tests the Host URL would be api.assertible.com. Or if you wanted to test a website, say https://assertible.com/plan - then the Host URL would be assertible.com.

Authentication

If the web service you are testing requires authentication to make requests, you can configure the default auth in the web service settings. When a test is created, it will automatically use the API's default auth. Tests also have settings to override the auth when necessary.

Assertible supports the following auth types:

  • Basic Auth
  • Digest Auth
  • oAuth v1.0a
  • oAuth v2.0
  • API Token Auth
  • No Auth

If you need to use an auth that is not supported, you can configure it directly in a request header for your test or use a setup step to capture pre-request variables.

NOTE variable syntax is supported in all auth fields

Heads up! Auth is stored in plain text; it is not encrypted. Please take care to use non-critical API tokens when creating web services and tests. We are working on a secure solution and will send out an email when it is deployed.

Schemes

Schemes are the HTTP protocols that your web service supports: either http or https or both. When a scheme is configured, tests for that web service will know which schemes are supported. You can set or override the scheme used on any test in the test configuration.

Hooks and automation

Automation is an importand aspect of testing web services. In Assertible, there are several different types of automation:

See more extensive docs on automation in our automation section.

Rate limit

The Rate limit setting is used to configure the maximum number of requests per second that will hit your web service when tests are run. This is useful for APIs and web apps that have built-in request throttling, and allows you to configure Assertible to abide by those limits. The default rate limit is 15 requests/s.

Throttling is done for all requests in a run ID. A single run ID may contain multiple tests (eg, 10 tests running on a schedule), and a test may make multiple requests (eg, with setup steps or a link checker assertion). In all of these cases, requests will be throttled to your service's rate limit setting.

The rate limit setting can be found on your web service's Settings tab, with the other primary service settings.

Note: Rate limiting is not done across different run IDs. For example, if two schedules run at the same time, they will be throttled independently.

Web Service Badges

Each web service has an embeddable badge for displaying the current status of all test assertions for the latest test runs. You can use this to communicate the current status of a web service with team members or within documentation pages.

Badges can be copied from a web services Settings tab under Service settings (there's even a link to directly copy markdown).

Fig 1.5 Embeddable web service badges

You can also create a badge for a specific environment like staging or production by using the environment query parameter on the trigger url.

Examples:

Badge monitoring production

https://assertible.com/apis/{{api-id}}/status?api_token={{token}}

Badge monitoring staging

https://assertible.com/apis/{{api-id}}/status?api_token={{token}}&environment=staging

Markdown:

[![Assertions Status](https://assertible.com/apis/{{api-id}}/status?api_token={{token}})]

HTML:

<img src="https://assertible.com/apis/{{api-id}}/status?api_token={{token}}" alt="Assertions Status" />

Environments

An environment is a unique host for a web service and contains the required settings for making requests to HTTP endpoints related to a web service (e.g. SSL validation and hostname).

For example, staging.assertible.com could correspond to an environment named staging whereas assertible.com would correspond to production.

Sections

Environments make it easy to run your API tests against different instances of your web service. When running tests from the dashboard, you can use the environment drop-down selector to set the current environment.

Assertible dashboard environment selector

When you change the environment from the dashboard using the drop-down selector, different views will be updated to only reflect the test result status for that specific environment There is a special selector named All environments which will not apply any filters to test results. When using All environments, any test run buttons will be run against the default environment.

Environment auth

In Assertible, a web service has a default auth that is used on every test. Environments can also specify their own default auth. When tests are run, the auth from the current environment will be used.

To configure default auth for an environment, visit the Environments section of the Settings tab for your web service:

Configure authentication for multiple environments in Assertible

An environment can also choose to use default API auth, which means tests run against that environment will use the default auth defined at the service level.

Learn more about configuring auth for your web service tests.

Environment variables

In Assertible, each environment can define a set of default variables which can be used by any test. Environment variables are useful for a number of use-cases including:

  • Representing seed data fixtures in pre-production and production environments.
  • Avoiding superfluous setup and teardown steps, making tests more robust and less flaky.
  • Reducing duplication of variables between tests
  • Reducing test maintenance by sharing common data

To configure variables for an environment, visit the Environments section of the Settings tab for your web service:

Configure variables for an environment in Assertible

Variable precedence

Similar to environment auth, variables have an established precedence to make it possible to override a variable on a specific test. The precedence is as follows:

  1. Test-level variables (highest precedence)
  2. Dynamic variables using setup steps
  3. Environment variables (lowest precedence)

For example, if you have a variable named user1-uuid in your environment, but create a new test and manually create a test variable with the same name, the test variable will be used and NOT the environment variable.

Furthermore, if you create a setup step which defines a user1-uuid dynamic variable, it will override both the test variable and environment variable with the same key.

Validate SSL

When the "Validate SSL" setting is enabled for a web service environment, validations are run on the SSL certificate for the request. For example, in the case of an SSL hostname mismatch or certificate expiration, the AssertValidSsl core assertion would fail.

Environments and integrations

Environments are used by Trigger URLs and the Deployments API to specify the unique host URL to use when your tests are executed.

The image below shows an example using the Deployments API with GitHub status checks enabled for a web service which was deployed to an environment named assertible-staging using the GitHub API.

Assertible GitHub status check

For more info about our Deployments API, GitHub integration, see the "How it works" documentation.

Transfer a web service

Note! When transferring a service, any integrations need to be re-installed on the new organization.

A web service can be transferred from a personal account to an organization. This is useful in cases where you've created a personal web service and are now ready to share and collaborate those tests with your team.

To transfer a web service, visit the Manage tab of your web service Settings. If the service is eligible to be transferred, you'll will see a form to select the new owner of the service. The new owner must be an organization that belong to.

Need help transferring your service to an organization? Reach out and we'll help you get set up!


The easiest way to test and
monitor your web services

Define and test your web service with Assertible Track and test API deployments across environments Schedule API monitoring and failure alerts

Reduce bugs in web applications by using Assertible to create an automated QA pipeline that helps you catch failures & ship code faster.

Sign up for free