Print

API Modelling – The API Definition Tree

After importing your first API host, JOSF automatically structures the imported data into what’s called the API Definition Tree. This tree forms the foundation for your API modelling work. It provides a clear overview of all available endpoints, resources, and requests derived from your service definition file.

The API Definition Tree consists of three main parts:

1. Endpoint URL

The endpoint URL represents the base address of your API.
This URL is automatically generated based on the imported service definition. Each endpoint in the tree serves as a container for one or more resources that belong to that host.

You cannot manually reorder endpoints within the tree. The structure is determined automatically based on the hierarchy of the service definition.

From the endpoint level, you can:

  • Add a new resource: Hover over the endpoint and click the plus icon, or right-click the endpoint and select Add Resource.

2. Resources

Resources act as blueprints for your actual API requests. Each resource represents a specific API path or functionality and contains information such as:

  • HTTP method (GET, POST, PUT, DELETE, etc.)
  • Path where the resource is located
  • SOAPAction (if applicable for SOAP services)

For more details about SOAPAction, see the W3C specification: https://www.w3.org.

Tags

Resources can be grouped and organized using tags. Tags help you maintain a clear overview, especially when working with larger APIs.

  • If a resource has tags, it will be grouped under the corresponding tag section.
  • Resources without tags are grouped under the no-tags group.
  • When a service definition includes predefined tags, JOSF will automatically apply them.

From the resource level, you can:

  • Add a new request: Hover over the resource and click the plus icon, or right-click and select Add Request.

3. Requests

Requests contain the actual data and configuration used to communicate with the API. A request may include several key elements:

  • Body: The payload of the request, typically in JSON or XML format.
  • Authorization: Credentials or tokens used for authentication.
  • Parameters: Query or path parameters used to specify request details.
  • Headers: Additional metadata sent along with the request.
  • Cookies: Any cookies required for session management.

When importing a service definition, JOSF automatically pre-fills the required fields—such as body templates, headers, and parameters—based on the information provided in the definition.

Request Actions

Within the API Definition Tree, you can:

  • Rename a resource or request: Right-click and select Rename request.
  • Duplicate a request: Right-click and select Duplicate Request.
  • Copy as CURL: Right-click a request and select Copy as CURL to copy the request to your clipboard. You can paste it into a terminal to execute it directly.
  • Remove a request: Right-click and select Remove Request.
  • Open model: Right-click or single-click a request to open and edit it.

Summary

The API Definition Tree in JOSF provides a clear and organized overview of your imported API.
It separates the API into endpoints, resources, and requests, making it easy to navigate, extend, and maintain.
By using the built-in options to add, duplicate, or modify requests, you can efficiently model your API and prepare it for execution or integration within your test cases.

Next topic: Request Modelling and Post Action Steps

In this document