Orgs registry

1. Introduction

The OrgObject API allows clients to manage organization metadata stored in MongoDB. It supports:

• Creating, retrieving, updating, and deleting organizations
• Filtering based on organization metadata, spec versions, tags, groups, etc.
• GraphQL endpoint for flexible queries

The service is intended to support registry-based, tagged, and spec-linked metadata for multiple organizations across systems.

OrgObject Schema

Data Class

@dataclass
class OrgObject:
    org_uri: str
    org_id: str
    org_spec_id: str
    org_local_db_url: str
    org_service_gateway_url: str
    org_asset_registry_id: str
    org_group_ids: List[str]
    org_name: str
    org_description: str
    org_metadata: Dict[str, Any]
    org_url_map: Dict[str, str]
    org_tags: List[str]
    org_spec_data: Dict[str, Any]

Field Description Table

Field Name	Type	Description
org_uri	str	Computed URI in the format <org_name>:<org_spec_id>
org_id	str	Unique organization identifier
org_spec_id	str	Versioned spec ID for configuration
org_local_db_url	str	Internal/local MongoDB or DB endpoint
org_service_gateway_url	str	URL to public-facing gateway for org services
org_asset_registry_id	str	Identifier for associated asset registry
org_group_ids	List[str]	Array of group IDs the org belongs to
org_name	str	Human-readable name
org_description	str	Text description
org_metadata	Dict[str, Any]	Arbitrary user-defined metadata
org_url_map	Dict[str, str]	Mapping of internal service URLs
org_tags	List[str]	Set of searchable tag keywords
org_spec_data	Dict[str, Any]	Complete specification document for the org

---

3. REST API Documentation

3.1 CRUD APIs

Create Organization

• POST /org

curl -X POST http://localhost:5000/org \
     -H "Content-Type: application/json" \
     -d '{
           "org_id": "org-001",
           "org_spec_id": "v1",
           "org_name": "ExampleOrg",
           "org_tags": ["ai", "research"]
         }'

---

Get Organization by URI

• GET /org/<org_uri>

curl http://localhost:5000/org/ExampleOrg:v1

---

Update Organization by URI

• PUT /org/<org_uri>

curl -X PUT http://localhost:5000/org/ExampleOrg:v1 \
     -H "Content-Type: application/json" \
     -d '{"org_description": "Updated org description"}'

---

Delete Organization by URI

• DELETE /org/<org_uri>

curl -X DELETE http://localhost:5000/org/ExampleOrg:v1

---

3.2 Generic Query

Query Organizations

• POST /orgs

curl -X POST http://localhost:5000/orgs \
     -H "Content-Type: application/json" \
     -d '{"org_tags": "research"}'

---

3.3 Specialized Queries

Get by org_id

• GET /orgs/by-id/<org_id>

curl http://localhost:5000/orgs/by-id/org-001

---

Get by org_spec_id

• GET /orgs/by-spec-id/<spec_id>

curl http://localhost:5000/orgs/by-spec-id/v1

---

Get by Tag

• GET /orgs/by-tag/<tag>

curl http://localhost:5000/orgs/by-tag/research

---

Get by Group ID

• GET /orgs/by-group/<group_id>

curl http://localhost:5000/orgs/by-group/group-xyz

---

Get by Asset Registry ID

• GET /orgs/by-registry/<registry_id>

curl http://localhost:5000/orgs/by-registry/registry-01

---

Search by Name Keyword

• GET /orgs/search-by-name?q=<keyword>

curl "http://localhost:5000/orgs/search-by-name?q=example"

---

Get by URL Prefix

• GET /orgs/with-url-prefix?prefix=<prefix>

curl "http://localhost:5000/orgs/with-url-prefix?prefix=http://gateway."

---

Get by Metadata Key/Value

• POST /orgs/by-metadata

curl -X POST http://localhost:5000/orgs/by-metadata \
     -H "Content-Type: application/json" \
     -d '{"key": "region", "value": "asia"}'

---

Get Organizations with Specific Key in org_spec_data

• GET /orgs/has-spec-key/<key>

curl http://localhost:5000/orgs/has-spec-key/runtime

---

4. GraphQL Endpoint

Endpoint

• POST /graphql

Supports:

• Querying by org_id, org_name, or tag
• Nested field retrieval
• GraphiQL UI via browser

Sample GraphQL Query

query {
  orgs(tag: "ai") {
    org_id
    org_name
    org_description
    org_tags
  }
}

Sample cURL

curl -X POST http://localhost:5000/graphql \
     -H "Content-Type: application/json" \
     -d '{"query": "query { orgs(tag: \"ai\") { org_id org_name } }"}'