WebProtégé API

The WebProtégé API

The WebProtégé backend uses asynchronous messaging for communication between services. We use Apache Pulsar for the messaging infrastructure. In what follows we talk about this messaging infrastructure in quite a general way, referring to message channels which are implemented in Apache Pulsar as topics.

To illustrate how this process works, let's consider a brief example. A typical WebAPI call to an endpoint involves sending a request message through one message channel, and subsequently, a response message is received at a later time via another message channel. The request message channels are predefined as part of the WebProtégé API, while the response message channels are determined by the caller. In other words, the responses are directed to the message channel specified by the caller.

Both requests and responses are messages that have payloads and headers. Message payloads are represented using JSON. They contain information that is specific to a request. Message headers are used for message routing (specifying a return message channel, for example) and authorization details.

As an illustrative example, consider a call that retrieves a particular frame for a particular class in a particular project. To do this we would post a message to the webprotege.frames.GetClassFrame message channel (as documented here). The message body would look something like this:

{
  "projectId":"6a6e6b1e-384c-4e19-bf64-d3a8c491ec1f",
  "subject"  : {
    "@type" : "Class",
    "iri"   : "http://example.org/A"
  }
}

The body specifies the relevant project and the desired frame subject, i.e. the class we're interested in.

As far as headers are concernted, we need to specify a reply channel using the webprotege_replyChannel message header. In this example for example we might set a reply channel as my-amazing-webprotege-service, i.e. something specific to our application so that replies to our request messages are delivered to a channel specific to us We also need to set a correlationId that ties a reponse to a request that we have made. We do this setting the webprotege_correlationId header. This value of this header should be a randomly generated UUID that is unique to the request. Finally, we need to specify an access token as an encoded JSON Web Token using the webprotege_accessToken header that provides details of the user making the request.

You can see this request/response, and others, in the API documents. We use the AsyncAPI specification for documentation.

Dependencies for Services Implemented in Java

The following table lists some dependencies that contain Java classes that represent the various requests and responses that can be made. To continue with the previous example, the webprotege-entity-frames-api dependency contains classes that represent messages for the GetClassFrame request and response.

Dependency Name (Maven Artifact Id)	Remarks	Relevant API Requests/Responses
webprotege-authorization-service-api	Request/Response objects for getting the authorization status for users	GetAssignedRolesResponse GetRolesRequest GetAuthorizedSubjectsRequest GetAuthorizedSubjectsResponse GetRolesResponse GetAuthorizedResourcesRequest GetAuthorizedActionsResponse GetAuthorizedResourcesResponse GetAuthorizedActionsRequest GetAssignedRolesRequest GetAuthorizationStatusRequest GetAuthorizationStatusResponse SetAssignedRolesRequest SetAssignedRolesResponse
webprotege-forms-api		CopyFormDescriptorsAction CopyFormDescriptorsResult CreateEntityFromFormDataAction CreateEntityFromFormDataResult DeleteFormAction DeleteFormResult DeprecateEntityByFormAction DeprecateEntityByFormResult GetEntityCreationFormsAction GetEntityCreationFormsResult GetEntityDeprecationFormsAction GetEntityDeprecationFormsResult GetEntityFormDescriptorAction GetEntityFormDescriptorResult GetEntityFormsAction GetEntityFormsResult GetProjectFormDescriptorsAction GetProjectFormDescriptorsResult SetEntityFormDescriptorAction SetEntityFormDescriptorResult SetEntityFormsDataAction SetEntityFormsDataResult SetProjectFormDescriptorsAction SetProjectFormDescriptorsResult UpdateFormDescriptorAction UpdateFormDescriptorResult
webprotege-backend-api	Currently a catch all. This will gradually be divided in the long run.	GetApplicationSettingsAction GetApplicationSettingsResult SetApplicationSettingsAction SetApplicationSettingsResult AddAxiomsRequest AddAxiomsResponse RemoveAxiomsRequest RemoveAxiomsResponse EditAnnotationsAction EditAnnotationsResult MoveEntitiesToParentAction MoveEntitiesToParentResult SetAnnotationValueAction SetAnnotationValueResult GetProjectChangesAction GetProjectChangesResult RevertRevisionAction RevertRevisionResult GetEntityCrudKitsAction GetEntityCrudKitSettingsAction GetEntityCrudKitSettingsResult GetEntityCrudKitsResult SetEntityCrudKitSettingsAction SetEntityCrudKitSettingsResult LookupEntitiesResult EntityLookupResult CreateNamedIndividualsResult CreateNamedIndividualsAction CreateAnnotationPropertiesAction GetDeprecatedEntitiesResult DeleteEntitiesResult EntityLookupRequest CreateDataPropertiesResult LookupEntitiesAction CreateClassesAction CreateDataPropertiesAction GetDeprecatedEntitiesAction CreateAnnotationPropertiesResult DeleteEntitiesAction CreateClassesResult CreateObjectPropertiesResult CreateObjectPropertiesAction MergeEntitiesAction MergeEntitiesResult SetEntityDeprecatedRequest SetEntityDeprecatedResponse GetHierarchyChildrenAction GetHierarchyChildrenResult GetHierarchyPathsToRootAction GetHierarchyPathsToRootResult GetHierarchyRootsAction GetHierarchyRootsResult GetHierarchySiblingsAction GetHierarchySiblingsResult GetIndividualsAction GetIndividualsPageContainingIndividualAction GetIndividualsPageContainingIndividualResult GetIndividualsResult GetEntityDiscussionThreadsResult CreateEntityDiscussionThreadAction DeleteCommentResult CreateEntityDiscussionThreadResult GetCommentedEntitiesResult GetEntityDiscussionThreadsAction DeleteCommentAction GetCommentedEntitiesAction SetDiscussionThreadStatusAction SetDiscussionThreadStatusResult UpdateCommentAction UpdateCommentResult GetProjectLangTagsAction GetProjectLangTagsResult MergeUploadedProjectAction MergeUploadedProjectResult GetUploadedOntologiesAction GetUploadedOntologiesResult MergeOntologiesAction MergeOntologiesResult GetOntologyAnnotationsAction GetOntologyAnnotationsResult GetRootOntologyIdAction GetRootOntologyIdResult ProcessOntologySourcesRequest ProcessOntologySourcesResponse SetOntologyAnnotationsAction SetOntologyAnnotationsResult GetPerspectiveDetailsAction GetPerspectiveDetailsResult GetPerspectiveLayoutAction GetPerspectiveLayoutResult GetPerspectivesAction GetPerspectivesResult ResetPerspectiveLayoutAction ResetPerspectiveLayoutResult ResetPerspectivesAction ResetPerspectivesResult SetPerspectiveDetailsAction SetPerspectiveDetailsResult SetPerspectiveLayoutAction SetPerspectiveLayoutResult SetPerspectivesAction SetPerspectivesResult GetAvailableProjectsWithPermissionAction GetAvailableProjectsWithPermissionResult GetProjectPrefixDeclarationsRequest GetProjectPrefixDeclarationsResponse MoveProjectsToTrashAction MoveProjectsToTrashResult RemoveProjectFromTrashAction RemoveProjectFromTrashResult SetProjectPrefixDeclarationsAction SetProjectPrefixDeclarationsResult GetProjectSettingsAction GetProjectSettingsResult SetProjectSettingsAction SetProjectSettingsResult GetEntityHtmlRenderingAction GetEntityHtmlRenderingResult GetEntityRenderingAction GetEntityRenderingResult GetHeadRevisionNumberAction GetHeadRevisionNumberResult GetRevisionSummariesAction GetRevisionSummariesResult GetSearchSettingsAction GetSearchSettingsResult PerformEntitySearchAction PerformEntitySearchResult SetSearchSettingsAction SetSearchSettingsResult GetProjectSharingSettingsAction GetProjectSharingSettingsResult SetProjectSharingSettingsAction SetProjectSharingSettingsResult CreateSnapshotRequest CreateSnapshotResponse AddProjectTagAction AddProjectTagResult GetEntityTagsAction GetEntityTagsResult GetProjectTagsAction GetProjectTagsResult SetProjectTagsAction SetProjectTagsResult UpdateEntityTagsAction UpdateEntityTagsResult GetEntityUsageAction GetEntityUsageResult GetUserIdCompletionsAction GetUserIdCompletionsResult GetProjectEntityGraphDefaultEdgeCriteriaAction GetProjectEntityGraphDefaultEdgeCriteriaResult GetUserProjectEntityGraphCriteriaAction GetUserProjectEntityGraphCriteriaResult SetEntityGraphActiveFiltersAction SetEntityGraphActiveFiltersResult SetUserProjectEntityGraphSettingsAction SetUserProjectEntityGraphSettingsResult GetWatchesAction GetWatchesResult SetEntityWatchesAction SetEntityWatchesResult
webprotege-entity-frames-api [GitHub]	Request/Response objects for getting and updating entity frames	GetAnnotationPropertyFrameAction GetAnnotationPropertyFrameResult GetClassFrameAction GetClassFrameResult GetDataPropertyFrameAction GetDataPropertyFrameResult GetNamedIndividualFrameAction GetNamedIndividualFrameResult GetObjectPropertyFrameAction GetObjectPropertyFrameResult GetOntologyFramesAction GetOntologyFramesResult UpdateAnnotationPropertyFrameAction UpdateAnnotationPropertyFrameResult UpdateClassFrameAction UpdateClassFrameResult UpdateDataPropertyFrameAction UpdateDataPropertyFrameResult UpdateNamedIndividualFrameAction UpdateNamedIndividualFrameResult UpdateObjectPropertyFrameAction UpdateObjectPropertyFrameResult