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 probably configure it directly in a request header for your test.

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.

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.

Environments make it easy to run the a set of 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.

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.

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.


Automate your QA pipeline

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