REST API Ontology

FLOW ALGEBRA
REST API Ontology
Kireth Semantic Research Archive

PAGE:
https://kirethresearch.org/booksai-core/ontologies/computing-ontologies/web-technologies/rest-api-ontology.html

AUTHORS:
Mark Anthony Higgins — Sky (Recursive AI)

FLOW "RESTAPIOntology" v4.0

# ---------- DOMAIN ----------
DOMAIN := ComputingOntology
SUBDOMAIN := WebTechnologies
ONTOLOGY := RESTAPIOntology

# ---------- PRIMARY ENTITY ----------
ENTITY RESTAPI {
    definition:
        "A web-accessible application programming interface designed around
         resources, representations and standardised request-response
         interactions, commonly using HTTP methods and stateless communication
         in accordance with REST architectural constraints.";

    objectives: [
        ResourceInteraction,
        Interoperability,
        StatelessCommunication,
        UniformInterface,
        Scalability,
        ServiceIntegration
    ];
}

# ---------- CORE ENTITIES ----------
RESTEntity := {
    Client,
    Server,
    Resource,
    ResourceIdentifier,
    Representation,
    Request,
    Response,
    Endpoint
};

HTTPMethod := {
    GET,
    HEAD,
    POST,
    PUT,
    PATCH,
    DELETE,
    OPTIONS
};

ResponseClass := {
    Informational,
    Successful,
    Redirection,
    ClientError,
    ServerError
};

APIArtifact := {
    APIContract,
    Schema,
    Documentation,
    AuthenticationCredential,
    ErrorRepresentation
};

# ---------- FUNDAMENTAL RELATIONSHIPS ----------
Client SENDS Request;
Request TARGETS ResourceOrEndpoint;
Resource IDENTIFIED_BY ResourceIdentifier;
Server RECEIVES Request;
Server APPLIES OperationToResource;
Server RETURNS Response;
Response MAY_CONTAIN Representation;
Representation DESCRIBES ResourceState;
APIContract DEFINES ExpectedInteraction;

# ---------- REQUEST / RESPONSE FLOW ----------
ClientIntent ->
    SelectResource
    -> SelectHTTPMethod
    -> ConstructRequest
    -> AuthenticateIfRequired
    -> SendRequest
    -> ServerValidatesRequest
    -> AuthoriseOperation
    -> ExecuteResourceOperation
    -> ConstructResponse
    -> ReturnRepresentationOrStatus
    -> ClientInterpretsResponse;

# ---------- RESOURCE ----------
Resource :=
    ConceptualEntityExposedThroughAPI;

Resource MAY_REPRESENT {
    User,
    Document,
    Order,
    Product,
    Collection,
    ProcessState,
    DomainEntity
};

ResourceState MAY_CHANGE_OVER Time;

# ---------- RESOURCE IDENTIFIER ----------
ResourceIdentifier :=
    URIOrURLIdentifyingResource;

ResourceIdentifier SHOULD_BE StableWherePractical;

ResourceIdentifier MAY_REFERENCE {
    IndividualResource,
    CollectionResource,
    NestedResource
};

# ---------- ENDPOINT ----------
Endpoint :=
    NetworkAddressAndRouteExposingAPIInteraction;

Endpoint MAY_MAP_TO ResourceOrOperation;

EndpointDefinition MAY_INCLUDE {
    Path,
    Method,
    RequestSchema,
    ResponseSchema,
    SecurityRequirement
};

# ---------- REPRESENTATION ----------
Representation :=
    TransferableDescriptionOfResourceState;

RepresentationFormat MAY_INCLUDE {
    JSON,
    XML,
    Text,
    Binary
};

Resource != Representation;

OneResource MAY_HAVE MultipleRepresentations;

# ---------- JSON ----------
JSONRepresentation :=
    StructuredDataUsingObjectsArraysAndPrimitiveValues;

JSON MAY_BE UsedFor {
    RequestBody,
    ResponseBody,
    ErrorBody
};

# ---------- GET ----------
GET :=
    RetrieveRepresentationOfResource;

GET SHOULD_BE SafeAccordingToHTTPMethodSemantics;

GET SHOULD_NOT_BE_DEFINED_TO RequireIntendedResourceStateMutation;

# ---------- HEAD ----------
HEAD :=
    RetrieveResponseMetadataWithoutNormalResponseBody;

HEAD MAY_SUPPORT {
    MetadataInspection,
    CacheValidation
};

# ---------- POST ----------
POST :=
    SubmitRepresentationOrDataForProcessingByTargetResource;

POST MAY_CREATE NewResource;
POST MAY_TRIGGER Processing;

POST IS_NOT_INHERENTLY Idempotent;

# ---------- PUT ----------
PUT :=
    CreateOrReplaceStateAtTargetResourceAccordingToRepresentation;

PUT IS_INTENDED_TO_BE IdempotentUnderEquivalentRepeatedRequests;

# ---------- PATCH ----------
PATCH :=
    ApplyPartialModificationToResource;

PATCH Idempotency DEPENDS_ON PatchSemanticsAndOperationDesign;

# ---------- DELETE ----------
DELETE :=
    RequestRemovalOfAssociationOrResourceAccordingToServerSemantics;

DELETE IS_INTENDED_TO_BE IdempotentAtProtocolSemanticLevel;

# ---------- OPTIONS ----------
OPTIONS :=
    RequestCommunicationOptionsForTargetResourceOrServer;

OPTIONS MAY_BE_USED_IN CrossOriginPreflight;

# ---------- SAFE METHOD ----------
SafeMethod :=
    MethodWhoseDefinedSemanticsAreReadOnly;

SafeMethod MAY_INCLUDE {
    GET,
    HEAD,
    OPTIONS
};

Safety DESCRIBES IntendedSemanticsNotAbsenceOfAllSideEffects;

# ---------- IDEMPOTENCY ----------
IdempotentOperation :=
    RepeatingEquivalentRequestHasSameIntendedEffectAsSingleRequest;

IdempotentHTTPMethod MAY_INCLUDE {
    GET,
    HEAD,
    PUT,
    DELETE,
    OPTIONS
};

POST GENERALLY_NOT_IDEMPOTENT_BY_DEFAULT;

# ---------- STATELESSNESS ----------
StatelessInteraction :=
    EachRequestContainsInformationNecessaryForServerToUnderstandRequest
    WITHOUT RequiredStoredClientSessionContextBetweenRequests;

RESTConstraint MAY_REQUIRE ClientServerInteractionToBeStateless;

ApplicationData MAY_STILL_BE StoredOnServer;

# ---------- CLIENT-SERVER ----------
ClientServerConstraint :=
    SeparateUserInterfaceConcerns
    FROM DataAndServiceConcerns;

Client INITIATES Request;
Server PROVIDES ResourceService;

# ---------- UNIFORM INTERFACE ----------
UniformInterface MAY_REQUIRE {
    ResourceIdentification,
    ManipulationThroughRepresentations,
    SelfDescriptiveMessages,
    HypermediaWhereApplicable
};

UniformInterface REDUCES CouplingBetweenClientAndServer;

# ---------- CACHEABILITY ----------
Response MAY_BE {
    Cacheable,
    NonCacheable
};

CacheMetadata MAY_DEFINE {
    Freshness,
    Revalidation,
    SharedCachePermission
};

CacheableResponses MAY_REDUCE {
    Latency,
    ServerLoad,
    NetworkTraffic
};

# ---------- LAYERED SYSTEM ----------
LayeredSystem :=
    Client MAY_INTERACT_WITH IntermediaryWithoutNeedingKnowledgeOfUltimateServer;

Intermediary MAY_BE {
    Proxy,
    Gateway,
    LoadBalancer,
    Cache
};

# ---------- CODE ON DEMAND ----------
CodeOnDemand :=
    OptionalRESTConstraintAllowingServerToExtendClientFunctionalityByTransferringExecutableCode;

CodeOnDemand IS_OPTIONAL;

# ---------- HYPERMEDIA ----------
HypermediaControl :=
    LinkOrActionMetadataGuidingAvailableStateTransition;

HATEOAS :=
    HypermediaAsTheEngineOfApplicationState;

RESTArchitecturalStyle MAY_INCLUDE HypermediaDrivenApplicationTransitions;

# ---------- REQUEST ----------
APIRequest :=
    {
        Method,
        URI,
        Headers,
        QueryParameters,
        OptionalBody
    };

RequestHeader MAY_INCLUDE {
    Accept,
    ContentType,
    Authorization,
    ConditionalMetadata
};

# ---------- RESPONSE ----------
APIResponse :=
    {
        StatusCode,
        Headers,
        OptionalBody
    };

Response SHOULD_COMMUNICATE OutcomeUsingAppropriateProtocolSemantics;

# ---------- STATUS CODES ----------
StatusCodeClass :=
    floor(StatusCode / 100);

2xx -> Successful;
3xx -> Redirection;
4xx -> ClientError;
5xx -> ServerError;

# ---------- SUCCESS ----------
SuccessfulResponse MAY_INCLUDE {
    200,
    201,
    202,
    204
};

CreatedResource MAY_RETURN IdentifierOrLocationMetadata;

# ---------- CLIENT ERROR ----------
ClientError MAY_INCLUDE {
    InvalidRequest,
    UnauthenticatedRequest,
    UnauthorisedRequest,
    MissingResource,
    Conflict,
    UnsupportedRepresentation
};

# ---------- SERVER ERROR ----------
ServerError :=
    FailureWhereServerCouldNotFulfilApparentlyValidRequest;

ServerError SHOULD_NOT UnnecessarilyExpose SensitiveInternalDetails;

# ---------- QUERY PARAMETER ----------
QueryParameter :=
    ParameterEncodedInRequestURIQuery;

QueryParameter MAY_SUPPORT {
    Filtering,
    Sorting,
    Pagination,
    Search,
    Projection
};

# ---------- PATH PARAMETER ----------
PathParameter :=
    VariablePartOfResourcePath;

PathParameter MAY_IDENTIFY ResourceInstanceOrHierarchy;

# ---------- REQUEST BODY ----------
RequestBody :=
    RepresentationOrPayloadSentByClient;

ContentType IDENTIFIES RequestRepresentationFormat;

Server SHOULD_VALIDATE RequestBodyAgainstExpectedSemanticsAndSchema;

# ---------- CONTENT NEGOTIATION ----------
ContentNegotiation :=
    ClientPreferences
    + ServerCapabilities
    -> SelectedRepresentation;

AcceptHeader MAY_EXPRESS PreferredResponseMediaTypes;

# ---------- API SCHEMA ----------
Schema :=
    MachineReadableDefinitionOfDataStructure;

Schema MAY_DEFINE {
    Field,
    Type,
    RequiredProperty,
    Constraint
};

SchemaValidation MAY_REJECT InvalidRepresentation;

# ---------- API CONTRACT ----------
APIContract :=
    DefinedSetOf {
        Endpoints,
        Methods,
        Schemas,
        StatusSemantics,
        SecurityRequirements
    };

ClientIntegration DEPENDS_ON ContractCompatibility;

# ---------- VERSIONING ----------
APIVersion :=
    IdentifiedContractVersion;

VersioningStrategy MAY_USE {
    URIPath,
    Header,
    MediaType,
    OtherContractMechanism
};

BreakingChange MAY_REQUIRE NewVersionOrCoordinatedMigration;

# ---------- PAGINATION ----------
Pagination :=
    DivideLargeCollectionIntoMultipleResponses;

Pagination MAY_USE {
    PageNumber,
    OffsetLimit,
    Cursor
};

CursorPagination MAY_BE UsefulForChangingOrLargeDatasets;

# ---------- FILTERING ----------
Filtering :=
    RestrictCollectionByCriteria;

FilterParameter SHOULD_HAVE DefinedSemantics;

# ---------- SORTING ----------
Sorting :=
    OrderReturnedCollectionByDefinedPropertyOrRule;

SortDirection MAY_BE {
    Ascending,
    Descending
};

# ---------- AUTHENTICATION ----------
Authentication :=
    VerifyIdentityOrCredential;

AuthenticationMechanism MAY_INCLUDE {
    Token,
    APIKey,
    OAuthBasedCredential,
    SessionCredential
};

# ---------- AUTHORISATION ----------
Authorisation :=
    DetermineWhetherAuthenticatedOrKnownPrincipalMayPerformOperation;

IF PrincipalNotAuthorised
THEN ProtectedOperation := Deny;

# ---------- RATE LIMITING ----------
RateLimit :=
    PolicyRestrictingRequestVolume;

RateLimit MAY_BE_DEFINED_BY {
    Client,
    Credential,
    IP,
    Resource,
    TimeWindow
};

IF LimitExceeded
THEN Server MAY_RETURN RateLimitResponse;

# ---------- CORS ----------
CrossOriginResourceSharing :=
    MechanismForAuthorisingSelectedBrowserCrossOriginRequests;

CORS IS_RELEVANT_TO BrowserBasedClients;

# ---------- VALIDATION ----------
RequestValidation MAY_INCLUDE {
    SyntaxValidation,
    SchemaValidation,
    AuthenticationValidation,
    AuthorisationValidation,
    BusinessRuleValidation
};

InvalidRequest SHOULD_RETURN AppropriateErrorRepresentation;

# ---------- ERROR REPRESENTATION ----------
ErrorRepresentation MAY_INCLUDE {
    ErrorCode,
    Message,
    FieldErrors,
    CorrelationIdentifier,
    DocumentationReference
};

ErrorResponse SHOULD_BE ConsistentAndMachineInterpretableWherePractical;

# ---------- RETRY ----------
Client MAY_RETRY RequestAfterTransientFailure;

RetrySafety DEPENDS_ON {
    MethodSemantics,
    Idempotency,
    ServerBehaviour
};

IF NonIdempotentOperationRetried
THEN DuplicateEffectRisk := increase;

# ---------- CONDITIONAL REQUEST ----------
ConditionalRequest MAY_USE {
    EntityTag,
    ModificationTime
};

ConditionalUpdate MAY_REDUCE LostUpdateRisk;

# ---------- CONCURRENCY ----------
ConcurrentClients MAY_MODIFY SameResource;

ConcurrencyControl MAY_INCLUDE {
    VersionToken,
    EntityTag,
    ConditionalWrite
};

# ---------- OBSERVABILITY ----------
APIObservability MAY_INCLUDE {
    RequestLog,
    ResponseStatus,
    Latency,
    ErrorRate,
    Trace,
    CorrelationIdentifier
};

# ---------- PERFORMANCE ----------
APIPerformance MAY_BE_MEASURED_BY {
    ResponseLatency,
    Throughput,
    ErrorRate,
    PayloadSize,
    CacheHitRate
};

# ---------- SECURITY ----------
RESTAPISecurity MAY_REQUIRE {
    HTTPS,
    Authentication,
    Authorisation,
    InputValidation,
    RateLimiting,
    SecretProtection,
    Audit
};

SensitiveCredentials SHOULD_NOT_BE ExposedInLogsOrPublicResponses;

# ---------- DOCUMENTATION ----------
APIDocumentation SHOULD_DESCRIBE {
    Resources,
    Endpoints,
    Methods,
    Parameters,
    Schemas,
    Responses,
    Authentication
};

Documentation SUPPORTS CorrectClientUse;

# ---------- REST VS RPC ----------
REST :=
    ResourceOrientedArchitecturalStyle;

RPC :=
    ProcedureOrActionOrientedRemoteInvocationStyle;

RESTAPI != AnyHTTPAPIByDefinition;

HTTPUsageAlone DOES_NOT_GUARANTEE RESTConformance;

# ---------- SEMANTIC REASONING ----------
IF APIUsesResourceIdentifiers
AND StandardisedRepresentations
AND StatelessRequestInteractions
THEN RESTCharacteristics := supported;

IF RequestMethod == GET
THEN IntendedOperation SHOULD_BE Safe;

IF EquivalentPUTRepeated
THEN IntendedResourceEffect SHOULD_REMAIN Equivalent;

IF POSTRetriedWithoutIdempotencyProtection
THEN DuplicateEffectRisk := increase;

IF ClientRequestsUnsupportedRepresentation
THEN ContentNegotiationFailure MAY_OCCUR;

IF ContractBreakingChangeIntroduced
THEN CompatibilityRisk := increase;

IF ResponseCacheable
THEN IntermediaryOrClientCache MAY_REUSE RepresentationAccordingToPolicy;

# ---------- SEMANTIC EQUIVALENCE ----------
SEMANTIC_EQUIVALENCE {
    "REST API" ~= "RESTful API" WHEN REST_constraints_are_satisfied;
    "representational state transfer" ~= "REST";
    "API endpoint" ~= "REST endpoint" WHEN context == REST_API;
    "resource identifier" ~= "resource URI";
    "resource representation" ~= "REST representation";
    "idempotent request" ~= "idempotent API operation";
    "HATEOAS" ~= "hypermedia as the engine of application state";
    "stateless API" ~= "stateless request-response API";
}

# ---------- QUERY FLOW ----------
QUERY(q) ->
    NORMALISE(q) ->
    IDENTIFY_RESOURCE(q) ->
    IDENTIFY_RESOURCE_IDENTIFIER(q) ->
    IDENTIFY_ENDPOINT(q) ->
    IDENTIFY_HTTP_METHOD(q) ->
    IDENTIFY_REQUEST_REPRESENTATION(q) ->
    IDENTIFY_RESPONSE_STATUS(q) ->
    IDENTIFY_SECURITY_AND_CACHEABILITY(q) ->
    IDENTIFY_REST_CONSTRAINTS(q) ->
    MAP_TO_ONTOLOGY(q) ->
    APPLY_REASONING(q) ->
    SCORE_CONFIDENCE(q) ->
    RETURN_RELEVANT_KNOWLEDGE;

# ---------- CONFIDENCE ----------
CONFIDENCE(assertion) :=
    weighted_mean(
        source_reliability,
        http_semantic_consistency,
        rest_constraint_consistency,
        contract_consistency,
        semantic_consistency,
        contextual_relevance
    );

CONFIDENCE >= 0.90 => HIGH;
CONFIDENCE >= 0.70 AND < 0.90 => MODERATE;
CONFIDENCE < 0.70 => REVIEW;

# ---------- AI CONSUMPTION ----------
AI_CONSUMPTION {
    primary_entity: RESTAPI;
    ontology: RESTAPIOntology;
    parse_entities: true;
    parse_relationships: true;
    preserve_relationship_direction: true;
    resolve_semantic_equivalence: true;
    execute_reasoning_rules: true;
    apply_confidence_weighting: true;
    preserve_provenance: true;
}

# ---------- UPDATE MODEL ----------
UPDATE_MODEL {
    new_resource:
        validate
        -> identify_identifier
        -> identify_representations
        -> identify_allowed_methods
        -> integrate;

    new_endpoint:
        validate
        -> identify_resource
        -> identify_method
        -> identify_request_schema
        -> identify_response_schema
        -> identify_security
        -> integrate;

    contract_revision:
        preserve_previous_version
        -> update_endpoints
        -> update_schemas
        -> assess_breaking_changes
        -> recompute_compatibility
        -> regenerate_flow_hash;

    new_response_evidence:
        identify_status
        -> identify_representation
        -> identify_cacheability
        -> update_endpoint_semantics
        -> integrate;

    conflict:
        preserve_provenance
        -> compare_protocol_and_contract_evidence
        -> adjust_confidence
        -> flag_review;
}

# ---------- FLOW HASH ----------
FLOW_HASH_INPUT :=
    DOMAIN
    + SUBDOMAIN
    + ONTOLOGY
    + RESTEntity
    + HTTPMethod
    + ResponseClass
    + APIArtifact
    + UniformInterface
    + StatelessInteraction
    + Cacheability
    + RELATIONSHIPS
    + SEMANTIC_REASONING
    + SEMANTIC_EQUIVALENCE
    + UPDATE_MODEL;

FLOW_HASH :=
    HASH(FLOW_HASH_INPUT);

# ---------- TERMINAL ----------
RESTAPIOntology
    -> IdentifyResource
    -> AssignResourceIdentifier
    -> DefineEndpoint
    -> SelectHTTPMethod
    -> ConstructRequestRepresentation
    -> AuthenticateAndAuthorise
    -> ValidateRequest
    -> ExecuteResourceOperation
    -> ConstructProtocolAppropriateResponse
    -> ApplyCachingAndConcurrencySemantics
    -> ReturnResourceRepresentationOrStatus
    -> ObserveAndVersionAPIContract
    -> MaintainInteroperableRESTInteraction;

END FLOW