Skip to main content

API Design Principles

The Thirdfort Client API follows industry-standard design patterns based on Google's API Improvement Proposals (AIPs). These guidelines ensure our API is consistent, predictable, and easy to integrate with.

Resource-Oriented Design​

Our API follows a resource-oriented architecture where:

  • Resources are the fundamental building blocks (Checks, Organizations, Teams, Findings)
  • Resources are organised in a hierarchical structure reflecting ownership relationships
  • Standard operations (Create, Get, List, Update, Delete) behave consistently across all resources

Resource Names​

Every resource has a unique, hierarchical name:

organizations/{org_id}/teams/{team_id}/checks/{check_id}

Use - as a wildcard to query across multiple parent resources:

organizations/-/teams/-/checks

Standard Methods​

Most resources support these standard CRUD operations:

MethodHTTP VerbPath PatternDescription
CreatePOST/{parent}/resourcesCreates a new resource
GetGET/{name=...}Retrieves a single resource
ListGET/{parent}/resourcesLists resources with pagination
UpdatePATCH/{name=...}Updates specific fields
DeleteDELETE/{name=...}Removes a resource

Custom Methods​

When standard CRUD operations don't fit, we use custom methods with a :verb suffix:

PatternExamplePurpose
:cancelPOST /checks/{id}:cancelIrreversible state transitions
:undeletePOST /checks/{id}:undeleteRestore soft-deleted resources
:reviewPOST /findings/{id}:reviewComplex state changes with metadata
:searchPOST /activityLogs:searchComplex queries beyond List filtering

Custom methods use POST and accept a request body.

Batch Operations​

For efficiency when working with multiple resources, we provide batch methods:

PatternExamplePurpose
:batchGetGET /checks:batchGet?names=...Retrieve multiple resources by name
:batchDeletePOST /checks:batchDeleteDelete multiple resources atomically
:batchReviewPOST /findings:batchReviewApply operations to multiple resources

Batch methods reduce network round-trips and can provide transactional guarantees.

Long-Running Operations​

Some operations take significant time to complete (e.g., batch deletions). These return an Operation resource that you can poll:

# 1. Start the operation
POST /v1alpha2/organizations/{org}/teams/{team}/checks:batchDelete
→ Returns: { "name": "operations/abc123", "done": false, ... }

# 2. Poll for completion
GET /v1alpha2/operations/abc123
→ Returns: { "name": "operations/abc123", "done": true, "response": {...} }

Singleton Resources​

Some resources exist as exactly one per parent (not a collection). These use a static name segment:

organizations/{org}/teams/{team}/checks/{check}/checkSummary

Singletons support Get but not Create, List, or Delete — they're automatically managed.

Filtering and Pagination​

Filtering​

List operations support the filter parameter with common expression syntax:

GET /v1alpha2/checks?filter=state="COMPLETE" AND create_time>"2024-01-01T00:00:00Z"

Pagination​

Large result sets are paginated. Use page_size and page_token:

# First page
GET /v1alpha2/checks?page_size=25
→ Returns: { "checks": [...], "next_page_token": "abc..." }

# Next page
GET /v1alpha2/checks?page_size=25&page_token=abc...

Field Masks​

Update operations use field masks to specify which fields to modify:

PATCH /v1alpha2/checks/{id}
{
  "notification_recipient": { "email": "new@example.com" },
  "update_mask": "notification_recipient"
}

Only specified fields are updated; others remain unchanged.

HTTP/JSON Mapping​

While our API is defined using Protocol Buffers (gRPC), all endpoints are accessible via REST/JSON:

gRPC ConceptREST Equivalent
Service methodsHTTP endpoints
Request messagesJSON request body
Response messagesJSON response body
google.protobuf.EmptyEmpty response (204 or )

Versioning​

The API uses a versioned path prefix:

  • Current version: /v1alpha2
  • Preview endpoints: Marked with PREVIEW visibility, subject to change

Preview endpoints are production-ready but may evolve before becoming stable.

Further Reading​