Reason Behind CallAnAPI Allowing Only One URL

[apreg]

I’m trying to understand the design choice behind CallAnAPI allowing only a single URL. When I need to work with multiple endpoints, I have to create separate actors for each. Could you clarify the reason for this limitation?
Is this due to a technical limitation, or is it an intentional design choice that fits better with the Screenplay pattern?

[jan-molak]

Thanks for raising this - it's a good question and comes up quite often when people start working with multiple APIs in the same test suite.

CallAnApi is intentionally configured with a default base URL to reduce configuration noise and repetition across your tests. In most scenarios, you're interacting with a single API, so having a shared base URL keeps your test code concise and easier to maintain.

That said, you're not locked into that base URL.

As described in the docs, you can still send requests to any other endpoint by specifying the full URL explicitly. Here's the example for reference:

import { actorCalled } from '@serenity-js/core'
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions'

await actorCalled('Apisitt')
  .whoCan(
    CallAnApi.at(baseURL)
  )
  .attemptsTo(
    Send.a(GetRequest.to(resourcePath)),
    Ensure.that(LastResponse.status(), equals(200)),
  )

What happens depends on how resourcePath is defined:

• If resourcePath is a full URL, it overrides the configured base URL entirely
• If it starts with /, it replaces any path portion of the base URL
• If it's a relative path without a leading slash, it gets appended to the base URL

Here’s how that plays out in practice:

baseURL	resourcePath	result
https://api.example.org/	/v1/users/2	https://api.example.org/v1/users/2
https://example.org/api/v1/	users/2	https://example.org/api/v1/users/2
https://example.org/api/v1/	/secure/oauth	https://example.org/secure/oauth
https://v1.example.org/api/	https://v2.example.org/	https://v2.example.org/

So in short: the base URL is there for convenience, not a limitation. When you need to call a different service, just pass a full URL and Serenity/JS will use it as-is.