Services

Services are the definitions published in the NetOrca catalogue — what consumers can order. Each service has a name, schema, lifecycle state, and belongs to a service owner team.

Accessed via client.services.

States

`state`	Description
`IN_SERVICE`	Fully available — consumers can create, modify, and delete items
`NO_NEW_SERVICE_ITEM`	No new requests accepted; existing items can still be modified or deleted
`NO_MODIFY_EXISTING_SERVICE_ITEM`	Consumers can only decommission existing items
`DECOMMISSIONED`	Fully retired; no new activity permitted

Model properties

Property	Type	Description
`id`	`int`	Service ID
`name`	`str`	Service name — derived from the JSON Schema `title` field at creation
`state`	`str`	Lifecycle state (see above)
`schema`	`dict`	ServiceConfig wrapper; the raw JSON Schema is at `schema['schema']`
`owner_id`	`int`	Owner team ID
`owner_name`	`str`	Owner team name
`tags`	`list[str]`	Tag strings attached to the service
`has_md`	`bool`	Whether a documentation file is attached
`minimum_version`	`int`	Minimum allowed declaration version
`enabled_notifications`	`bool`	Whether event notifications are enabled

Methods

`list(**filters)`

Returns a lazy generator that iterates all services, fetching pages on demand. Accepts the same filters as filter(). Use this when iterating large result sets without loading everything into memory.

Filters:

Filter	Type	Description
`name`	`str`	Partial name match
`name_exact`	`str`	Exact name match
`owner_id`	`int`	Filter by owner team ID
`tags`	`str`	Filter by tag
`application_id`	`int`	Filter by application ID
`consumer_team_id`	`int`	Filter by consumer team ID
`service_item_id`	`int`	Filter to services that have this service item
`include_decommissioned`	`bool`	Include decommissioned services (default: `False`)
`ordering`	`str`	Sort field — prefix with `-` for descending (e.g. `name`, `-modified`)

for service in client.services.list():
    print(service.name, service.state)

# Services tagged "database"
for service in client.services.list(tags="database"):
    print(service.name, service.state)

# Sorted by name
for service in client.services.list(ordering="name"):
    print(service.name)

`filter(**filters)`

Same as list() but returns all results as a list instead of a generator. Useful when you need random access or need to count results. Accepts the same filters.

# All services owned by a specific team
services = client.services.filter(owner_id=7)

# Services tagged "storage", sorted by most recently modified
services = client.services.filter(tags="storage", ordering="-modified")

# Find a service by exact name
results = client.services.filter(name_exact="database-service")

print(f"Found {len(services)} services")

`get(id)`

Retrieves a single service by its ID. Raises NetorcaNotFoundError if the ID does not exist.

Parameter	Type	Description
`id`	`int`	Service ID

service = client.services.get(45)

print(service.id)
print(service.name)
print(service.state)
print(service.owner_name)
print(service.tags)
print(service.schema)

`create(data)`

Creates a new service. The payload is a raw JSON Schema document — the schema title becomes the service name. Returns the created Service object.

service = client.services.create({
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/database-service.schema.json",
    "type": "object",
    "title": "database-service",
    "description": "Provision managed databases on demand.",
    "required": ["engine", "size"],
    "properties": {
        "engine": {"type": "string", "enum": ["postgres", "mysql"]},
        "size":   {"type": "string", "enum": ["small", "medium", "large"]}
    }
})
print(service.id, service.name)

`update(id, data, partial=True)`

Updates an existing service. By default uses PATCH — only the fields you supply are changed. Pass partial=False to use PUT, which requires all fields.

Parameter	Type	Description
`id`	`int`	Service ID
`data`	`dict`	Fields to update
`partial`	`bool`	`True` (default) = PATCH, `False` = PUT

# Change the state to stop accepting new requests
client.services.update(45, {"state": "NO_NEW_SERVICE_ITEM"})

# Update title and description
client.services.update(45, {
    "title": "Managed Database (PostgreSQL)",
    "description": "PostgreSQL-only now. MySQL is being retired."
})

`delete(id)`

Not supported. The API does not permit deleting services. Calling this method raises NotImplementedError.

To retire a service, set its state to DECOMMISSIONED via update():

client.services.update(45, {"state": "DECOMMISSIONED"})

`validate(data)`

Validates a JSON Schema without creating a service. Takes the same raw JSON Schema format as create(). Returns {"is_valid": true} on success or a dict with errors on failure.

result = client.services.validate({
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "my-service",
    "required": ["name"],
    "properties": {
        "name": {"type": "string"}
    }
})
print(result)  # {"is_valid": true}

`submit(data)`

Creates or updates a service in one call — if a service with that title already exists it is updated; otherwise it is created. Takes the same raw JSON Schema format as create(). Returns the Service object.

service = client.services.submit({
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "title": "database-service",
    "description": "Provision managed databases on demand.",
    "required": ["engine"],
    "properties": {
        "engine": {"type": "string", "enum": ["postgres", "mysql"]}
    }
})
print(service.id)

`get_docs(service_id)`

Returns the documentation file attached to a service (if any). The documentation is typically a Markdown file uploaded via create_docs().

docs = client.services.get_docs(service_id=45)
print(docs)

`create_docs(service_id, file_path, upload_filename)`

Uploads a Markdown file and attaches it to a service as its documentation. The file will be displayed to consumers browsing the catalogue.

Parameter	Type	Description
`service_id`	`int`	Service to attach the doc to
`file_path`	`str`	Local path to the Markdown file
`upload_filename`	`str`	Filename to use on the server (e.g. `database-service.md`)

client.services.create_docs(
    service_id=45,
    file_path="/path/to/README.md",
    upload_filename="database-service.md"
)

`get_tags()`

Returns a list of all tag strings currently in use across all services. Useful for building a tag picker or auditing which tags exist.

tags = client.services.get_tags()
print(tags)  # ["database", "storage", "networking", ...]

`get_dependant()`

Returns services that have a declared dependency on this service. The return value is a list of raw dicts (not Service objects).

dependants = client.services.get_dependant()
for dep in dependants:
    print(dep)