Conceptual Model

API Messages

Fundamentally, API clients and the API service exchange XML-encoded ApiMessages over HTTP.

The API client sends an ApiRequest XML document to the primary API endpoint and receives an ApiResponse XML document, which can be in either XML Document or ZIP Bundle format.

ApiRequest	ApiResponse
wraps actions	wraps results

API Actions

API actions allow the client to specify the desired processing of the API service. Each ApiRequest can contain zero, one, or multiple actions.

An empty ApiRequest with zero actions can be used to verify the readiness of the API service.

Initial Actions

Initial actions must be wrapped in an Action element, and the mandatory type attribute triggers the associated processing in the API service. The payload of the Action element describes the desired processing and must be a well-formed and valid XML fragment conforming to the associated XSD schema for that action.

Some actions support the Representation element to specify the desired result structure.

Search actions introduce the concept of item facets to represent additional associated data related to the search result item.

Continuations

Continuation actions are special XML elements produced by the API service. They contain opaquely encoded information required for the continuation of processing. For example, search actions can produce NextPage continuations for the delivery of the next page of result items (see full traversal).

To invoke the processing of a continuation, the API client can include the entire unmodified Continuation element from the Result in a follow-up ApiRequest. In particular, the mandatory name attribute must not be altered.

API Results

For each action in the ApiRequest, there will be a corresponding result in the ApiResponse. The actions and results are matched in document order; that is, the first result corresponds to the first action, the second to the second, and so forth.

In addition to the success attribute, the structure of an ApiResult includes the following optional elements:

• Log: Collects LogEntry elements if present.

• Continuations: Includes possible continuation actions (e.g., NextPage for search actions).

• ResultData: Contains data elements (XML, text, binary, or reference information) to return the result of the action processing. The Meta element conveys information such as the paging progress. Composite data can be structured with the DataBag element (e.g., for separating different result items when delivering multiple item facets).

---

        ---
config:
  class:
    hideEmptyMembersBox: true

---
classDiagram

namespace message {
  class ApiRequest:::style_message {
    content: XML
  }
  class ApiResponse:::style_message {
    content: XML
  }
  class ResponseBundle:::style_message {
    <<ZIP>>
  }
  class BundleEntry:::style_message {
    path: string
    data: byte[]
  }
  class ApiResponseBundleEntry:::style_message {
    path: "/response.xml"
  }
}
classDef style_message fill:#faf;
BundleEntry <|-- ApiResponseBundleEntry
ResponseBundle *--> "1..n" BundleEntry
ResponseBundle *--> "1" ApiResponseBundleEntry : response
ApiResponseBundleEntry ..> "1" ApiResponse : contains
ApiResponse --> "1" ApiRequest

namespace data {
  class ResultData:::style_data {
    <<interface>>
    id?: token
    role?: token
    context?: token
  }
  class Meta:::style_data
  class DataBag:::style_data
  class Data:::style_data {
    xmlProcessContents: "strict"
    data: XML
  }
  class DataLax:::style_data {
    xmlProcessContents: "lax"
    data: XML
  }
  class DataAny:::style_data {
    xmlProcessContents: "skip"
    data: XML
  }
  class DataText:::style_data {
    type?: MIME
    data: string
  }
  class DataBinary:::style_data {
    type?: MIME
    checksum?: string
    data: byte[]
  }
  class DataReference:::style_data {
    type?: MIME
    checksum?: string
    target: URI
  }
  class BundleReference:::style_data
}
classDef style_data fill:#ffa;
ResultData <|.. DataBag
DataBag *--> "0..n" ResultData : data
ResultData <|.. DataAny
ResultData <|.. DataLax
ResultData <|.. Data
Data <|-- Meta
ResultData <|.. DataText
ResultData <|.. DataBinary
ResultData <|.. DataReference
DataReference <|-- BundleReference
BundleReference --> "1" BundleEntry : entry

namespace common {
  class Representation:::style_common {
    itemBags?: boolean
    images?: ResourceAction = LINK
    details?: DetailLevel = DEFAULT
    strictness?: ProcessingMode = STRICT
  }
  class Resource:::style_common {
    role?: token
    action: ResourceAction
  }
  class ResourceAction:::style_common {
    <<enumeration>>
    LINK
    EMBED
    BUNDLE
    DATA_URL
    SKIP
  }

  class DetailLevel:::style_common {
    <<enumeration>>
    MINIMAL
    OPTIMIZE_SPEED
    DEFAULT
    MAXIMAL
  }

  class ProcessingMode:::style_common {
    <<enumeration>>
    SKIP
    LAX
    STRICT
  }
}
classDef style_common fill:#faa;
Representation --> "1" DetailLevel
Representation --> "1" ProcessingMode
Representation --> "0..n" Resource
Resource --> "1" ResourceAction


namespace search {
  class Page:::style_search {
    size: int
  }
  class TopQuery:::style_search {
    slice: string = "1/1"
  }
  class Query:::style_search {
    <<interface>>
  }
  class SimpleQuery:::style_search {
    <<interface>>
  }
  class Id:::style_search
  class Any:::style_search
  class LastUpdate:::style_search
  class DefinedFieldsQuery:::style_search {
    <<interface>>
  }
  class UndecoratedQuery:::style_search {
    <<interface>>
  }
  class DecoratedQuery:::style_search {
    <<interface>>
  }
  class Require:::style_search
  class Exclude:::style_search

  class CompoundQuery:::style_search {
    <<interface>>
  }
  class And:::style_search
  class Or:::style_search
  class Not:::style_search

  class Sort:::style_search
  class SortField:::style_search {
    <<interface>>
    order: "Ascending" | "Descending"
  }
  class RelevanceSort:::style_search
  class LastUpdateSort:::style_search
}
classDef style_search fill:#f88;
Query <|-- DecoratedQuery
Query <|-- UndecoratedQuery
UndecoratedQuery <|-- SimpleQuery
UndecoratedQuery <|-- CompoundQuery
CompoundQuery <|.. Or
CompoundQuery <|.. And
CompoundQuery <|.. Not

SimpleQuery <|.. Id
SimpleQuery <|.. Any
SimpleQuery <|.. LastUpdate
SimpleQuery <|-- DefinedFieldsQuery
note for DefinedFieldsQuery "extension point for additional search criteria"

DecoratedQuery *--> "1" SimpleQuery : query
DecoratedQuery <|.. Require
DecoratedQuery <|.. Exclude

TopQuery *--> "1..n" Query : disjunctiveQueries
Or *--> "1..n" Query : queries
And *--> "1..n" Query : queries
Not *--> "1" Query : query

Sort *--> "1..4" SortField : criteria
SortField <|.. RelevanceSort
SortField <|.. LastUpdateSort
note for SortField "extension point for additional sort criteria"

namespace action {
  class Action:::style_action {
    <<interface>>
  }

  class InitialAction:::style_action {
    <<interface>>
    type: string
    content: XML
  }

  class Continuation:::style_action {
    name: string
    content: string
  }

  class SearchAction:::style_action {
    <<interface>>
    representation: Representation
    paging: Page
    query: TopQuery
    sorting: Sort
  }

  class Echo:::style_action
  class QuotaStatus:::style_action
  class TrademarkSearch:::style_action
  class PatentSearch:::style_action
}
classDef style_action fill:#afa;
ApiRequest *--> "0..n" Action : actions
Action <|-- InitialAction
Action <|.. Continuation
InitialAction <|.. Echo
InitialAction <|.. QuotaStatus
InitialAction <|-- SearchAction
SearchAction <|.. TrademarkSearch
SearchAction <|.. PatentSearch
SearchAction *--> "0..1" Representation : representation
SearchAction *--> "0..1" Page : paging
SearchAction *--> "1" TopQuery : query
SearchAction *--> "0..1" Sort : sorting

namespace result {
  class Result:::style_result {
    success: boolean
  }
  class LogEntry:::style_result
}
classDef style_result fill:#aaf;
ApiResponse *--> "0..n" Result : results
Result --> "1" Action : action
Result *--> "0..n" LogEntry : logs
Result *--> "0..n" Continuation : continuations
Result *--> "0..n" ResultData : data
    

Conceptual Overview