This is the codeAbility Sharing Platform! Learn more about the codeAbility Sharing Platform.

Skip to content

Changes

Page history
Update Connector Interface authored by Michael Breu's avatar Michael Breu
Hide whitespace changes
Inline Side-by-side
Artemis-Connection/Connector-Interface.md
View page @ 87e90692
# Sharing Plattform Connector Interface (V0.1)
In order to integrate functionality from other services into the sharing platform, the sharing platform provides a **connector interface** to exchange information with theses services.
Potential usage scenarios could be:
- export one or more exercises (meta data of the complete git project into other platforms (e.g. into Artemis)
- support the generation of pdf-documents from a selection of latex exercises
- implement own search interfaces
## Concepts
### Basics
A **Connected Service** is a web service on its own. I.e. it runs independently from the sharing platform in its own environment.
The Connected Service communicates with the sharing platform via the **Connector Interface**. The Connector Interface is a set of dedicated web services and also some protocols that involve redirects via the web browser of the user.
A Connected Service may support various **actions**. Each action provides is own callback url.
It is in the responsibility of the connector, to ensure the authentication and/or authorization of the user, if needed.
Some interfaces may require explicit authentication of the user of the connected service. A user is typically authenticated by a valid oAuth2-token of the backbone gitlab system.
### Configuration
An administrator of the sharing platform registers a _connector action_ (with a given plugin-URL).
This plugin-URL is used to retrieve further json-encoded configuration data for the action and to transfer callback information for the sharing plattform by invoking the registered URL with further parameters (e.g. `https://artemis.codeablity.uibk.ac.at/api/sharing/config?apiBaseUrl=http://localhost:8080/api/&installationName=SharingPlatformTest`):
```json
{
"version" : "0.1", // the version of the supported sharing plattform interface (currently fixed at 0.1)
"pluginName" : "Artemis Sharing Connector", // The name of the plugin
"actions" : [ { // list of supported actions
"actionId" : "Import", // the id of the action
"actionName" : "Import to Artemis", // the name of the action (displayed in the web browser)
"actionTransferURL" : "/sharingImport", // a call back url, to initiate the action (absolute, or relative to the URL of
// this configuration.
// a filter expression (formulated in Java EL) to select the exercises on the plattform
// to which the action is applicable
"filterELExpression" : "metadata.type.externalName=='programming exercise'"
} ]
}
```
When invoking the configuration, the sharing plattform transfers additional request parameters (and authorization headers) for further information:
- apiBaseUrl: the base url for the call backs to the sharing plattform (e.g. ´https://sharing.codeability-austria.uibk.ac.at/api´)
- installationName: an informative name for the current installation (e.g. `sharing plattform (prod)`
- optional: an a `Authorization` header: an optional bearer security token
### Exchanged Data
The Plugin Interface will exchange various data. A description of the REST Api can be found at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html (_at the time of writing under preparation_)
The main information item transferred is the shopping basket:
- **User**: Information about the requesting user
- **ShoppingBasket**: the currently selected items to be shared
- **ExerciseInfo**: Contains metadata about the exercise (coverage to be defined). And a reference to the GitLab URL
```plantuml
class User {
String email
}
' note top of User : Users should be authenticated via OAuth2 (authenticationURL)
class ShoppingBasket {
}
class Exercise {
String title
String gitLabURI
String gitLabProjectId
String[] keywords
}
User -> ShoppingBasket
ShoppingBasket "1" *-- "many" Exercise
```
- **SearchRequestDTO**: Query and User Information for a search via the sharing platform
- **UserPrincipal**: name and (optional) gitLabAccessToken for information retrieval
- **SearchInputDTO**: the search query
- **SearchInputMetadataDTO**: search query on meta data
- **SharingResultsDTO**: Results of a query (paged by page size of 10)
- **SharingResultDTO**: A single search hit
- **GitProject**: Information about the git project containing this hit
- **MetadataFile**: Information about meta data file
- **UserProvidedMetadataDTO**: the meta data itself
```plantuml
class SearchRequestDTO {
}
class UserPrincipal {
}
class SearchInputDTO {
}
class SearchInputMetadataDTO {
}
SearchRequestDTO --> SearchInputDTO
SearchInputDTO --> SearchInputMetadataDTO
SearchRequestDTO -down-> UserPrincipal
class SharingResultsDTO{
}
class SharingResultDTO{
}
class GitProject {
}
class MetadataFile {
}
class UserProvidedMetadataDTO {
}
SharingResultsDTO --> "0..10" SharingResultDTO
SharingResultDTO --> GitProject
SharingResultDTO --> MetadataFile
SharingResultDTO --> UserProvidedMetadataDTO
```
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
```plantuml
class SharingPluginConfig {
String version (fixed to 0.1)
String pluginName
}
class Action {
String actionId
String actionName
String actionTransferURL
String filterELExpression
}
SharingPluginConfig "1" *-- "many" Action
```
The java binding of the interface is provided in https://sharing-codeability.uibk.ac.at/development/sharing/codeabilitysharingpluginapi
## Infrastructure
Typically a connected service provides its own web interface.
The communication between the sharing platform and the connected service is done via a REST service.
## Exchange Protocol
### Main action initiation logic
When the filter condition matches on an exercise, the user can invoke the respective action on the exercise: e.g. here the export action for Artemis on all exercises that have the format artemis.
![image](uploads/d1be1e3daacc67af5a504954e76772a0/image.png)
An action is typically invoked by redirecting the web browser in the sharing platform to the actionTransferURL.
The actionTransferURL is extended by the basket token and the following query parameters, to be processed further by the plugin:
- **apiBaseURL**: the baseURL for the plugin REST api. All REST requests should be made relative to this URL
- **returnURL**: an URL to be optionally used, to redirect the browser back to the sharing plattform.
(e.g. http://artemis.codeability.uibk.ac.at/sharingImport/6321ab93-e597-4afe-a675-9c3e695814da?returnURL=http://artemis.codeability.uibk.ac.at&apiBaseURL=http://localhost:8080/api/pluginIF/v0.1)
**Remark**: Due to browser restriction the plugin URL is currently not loaded in a separate window, but in the same window, replacing the sharing plattform web page.
```plantuml
package "Sharing Platform" {
[Sharing Web Page] .. () "WebInterface S"
() "WebInterface S" -- [Sharing Platform]
[Sharing Platform] - () "REST Interface S"
}
package "plugin" {
[Plugin Web Page] .. () "WebInterface P" : "(2) GET"
() "WebInterface P" -- [Plugin Application]
() "REST Interface P" - [Plugin Application]
}
[Sharing Web Page] ..> [Plugin Web Page]: "(1) invoke via actionTransferURL (+ BasketToken + further Parameters)"
()"REST Interface S" <.. [Plugin Application] : "(3) get action parameters"
```
Below you find a sketch of the basic process of the the invocation of a plugin action.
The action is initiated by a browser-based forward to the plugin web page, that contains a token to identify the basket and the URI to call back the REST interface.
**Remark**: The process can also work completely without a web interface of the plugin. Then the actionTransferURL is just an invocation of an REST interface.
```plantuml
actor "User Browser"
== Initialization (and regular heart beat monitoring) ==
"Sharing Plattform" -> Connector : REST config URL
Connector --> "Sharing Plattform" : SharingPluginConfig
== Shopping Session ==
[-> "User Browser"** : start session
"User Browser"-> "Sharing Plattform" : fill shopping basket
"User Browser"-> "Sharing Plattform" : trigger Action
"Sharing Plattform" --> "User Browser": redirect to action.actionTransferURL + "/<basketToken>?" + "apiBaseURL="<apiBaseURL> + "&returnURL=..."
"User Browser"-> Connector : action.actionTransferURL + "/<basketToken>?" + ...
activate Connector
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>
"Sharing Plattform" --> Connector: ShoppingBasket
Connector -> Connector: evaluate Basket, do Work
activate Connector #DarkSalmon
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>/repository/<exerciseId>
"Sharing Plattform" --> Connector: Zipped repository (master, latest commit)
Connector --> "User Browser": Result (HTML, PDF, ..., further actions)
deactivate Connector
Connector --> "User Browser": Optional - redirect to <returnURL>
deactivate Connector
```
## REST interface provided by the sharing Plattform
You can find a description of the current API with Swagger-UI at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html
The following REST services are provided: (**Remark**: https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1 is just an example REST url, this must be replaced by the *apiBaseURL* submitted via the actionTransferURL.)
1. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/<basketToken>
returns the Shopping Basket for this basketToken.
2. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/<basketToken>/repository/<exerciseId>
returns the zipped content of the current master branch of the exercise repository.
Please note, the content of the file currently contains the repository identically as the *download functionality* in the git lab repository, but the (redundant) main folder is eliminated. I.e. when unzipping the layout is identical iff cloned directly from the repository (however the .git information is missing).
3. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/page-details gets a SearchRequestDTO and returns the corresponding SearchResultsDTO.
# Sharing Plattform Connector Interface (V0.1)
In order to integrate functionality from other services into the sharing platform, the sharing platform provides a **connector interface** to exchange information with theses services.
Potential usage scenarios could be:
- export one or more exercises (meta data of the complete git project into other platforms (e.g. into Artemis)
- support the generation of pdf-documents from a selection of latex exercises
- implement own search interfaces
For historical reasons the connector is also referred as "plugin".
## Concepts
### Basics
A **Connected Service** is a web service on its own. I.e. it runs independently from the sharing platform in its own environment. The Connected Service communicates with the sharing platform via the **Connector Interface**. The Connector Interface is a set of dedicated web services and also some protocols that involve redirects via the web browser of the user.
A Connected Service may support various **actions**. Each action provides is own callback url.
It is in the responsibility of the connector, to ensure the authentication and/or authorization of the user, if needed. Some interfaces may require explicit authentication of the user of the connected service. A user is typically authenticated by a valid oAuth2-token of the backbone gitlab system.
### Configuration
An administrator of the sharing platform registers a _connector action_ (with a given plugin-URL).
This plugin-URL is used to retrieve further json-encoded configuration data for the action and to transfer callback information for the sharing plattform by invoking the registered URL with further parameters (e.g. `https://artemis.codeablity.uibk.ac.at/api/sharing/config?apiBaseUrl=http://localhost:8080/api/&installationName=SharingPlatformTest`):
```json
{
"version" : "0.1", // the version of the supported sharing plattform interface (currently fixed at 0.1)
"pluginName" : "Artemis Sharing Connector", // The name of the plugin
"actions" : [ { // list of supported actions
"actionId" : "Import", // the id of the action
"actionName" : "Import to Artemis", // the name of the action (displayed in the web browser)
"actionTransferURL" : "/sharingImport", // a call back url, to initiate the action (absolute, or relative to the URL of
// this configuration.
// a filter expression (formulated in Java EL) to select the exercises on the plattform
// to which the action is applicable
"filterELExpression" : "metadata.type.externalName=='programming exercise'"
} ]
}
```
When invoking the configuration, the sharing plattform transfers additional request parameters (and authorization headers) for further information:
- apiBaseUrl: the base url for the call backs to the sharing plattform (e.g. ´https://sharing.codeability-austria.uibk.ac.at/api´)
- installationName: an informative name for the current installation (e.g. `sharing plattform (prod)`
- optional: an a `Authorization` header: an optional bearer security token
### Exchanged Data
The Plugin Interface will exchange various data. A description of the REST Api can be found at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html (_at the time of writing under preparation_)
The main information item transferred is the shopping basket:
- **User**: Information about the requesting user
- **ShoppingBasket**: the currently selected items to be shared
- **ExerciseInfo**: Contains metadata about the exercise (coverage to be defined). And a reference to the GitLab URL
```plantuml
class User {
String email
}
' note top of User : Users should be authenticated via OAuth2 (authenticationURL)
class ShoppingBasket {
}
class Exercise {
String title
String gitLabURI
String gitLabProjectId
String[] keywords
}
User -> ShoppingBasket
ShoppingBasket "1" *-- "many" Exercise
```
- **SearchRequestDTO**: Query and User Information for a search via the sharing platform
- **UserPrincipal**: name and (optional) gitLabAccessToken for information retrieval
- **SearchInputDTO**: the search query
- **SearchInputMetadataDTO**: search query on meta data
- **SharingResultsDTO**: Results of a query (paged by page size of 10)
- **SharingResultDTO**: A single search hit
- **GitProject**: Information about the git project containing this hit
- **MetadataFile**: Information about meta data file
- **UserProvidedMetadataDTO**: the meta data itself
```plantuml
class SearchRequestDTO {
}
class UserPrincipal {
}
class SearchInputDTO {
}
class SearchInputMetadataDTO {
}
SearchRequestDTO --> SearchInputDTO
SearchInputDTO --> SearchInputMetadataDTO
SearchRequestDTO -down-> UserPrincipal
class SharingResultsDTO{
}
class SharingResultDTO{
}
class GitProject {
}
class MetadataFile {
}
class UserProvidedMetadataDTO {
}
SharingResultsDTO --> "0..10" SharingResultDTO
SharingResultDTO --> GitProject
SharingResultDTO --> MetadataFile
SharingResultDTO --> UserProvidedMetadataDTO
```
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
```plantuml
class SharingPluginConfig {
String version (fixed to 0.1)
String pluginName
}
class Action {
String actionId
String actionName
String actionTransferURL
String filterELExpression
}
SharingPluginConfig "1" *-- "many" Action
```
The java binding of the interface is provided in https://sharing-codeability.uibk.ac.at/development/sharing/codeabilitysharingpluginapi
## Infrastructure
Typically a connected service provides its own web interface.
The communication between the sharing platform and the connected service is done via a REST service.
## Exchange Protocol
### Main action initiation logic
When the filter condition matches on an exercise, the user can invoke the respective action on the exercise: e.g. here the export action for Artemis on all exercises that have the format artemis.
![image](uploads/d1be1e3daacc67af5a504954e76772a0/image.png)
An action is typically invoked by redirecting the web browser in the sharing platform to the actionTransferURL. The actionTransferURL is extended by the basket token and the following query parameters, to be processed further by the plugin:
- **apiBaseURL**: the baseURL for the plugin REST api. All REST requests should be made relative to this URL
- **returnURL**: an URL to be optionally used, to redirect the browser back to the sharing plattform. (e.g. http://artemis.codeability.uibk.ac.at/sharingImport/6321ab93-e597-4afe-a675-9c3e695814da?returnURL=http://artemis.codeability.uibk.ac.at&apiBaseURL=http://localhost:8080/api/pluginIF/v0.1) **Remark**: Due to browser restriction the plugin URL is currently not loaded in a separate window, but in the same window, replacing the sharing plattform web page.
```plantuml
package "Sharing Platform" {
[Sharing Web Page] .. () "WebInterface S"
() "WebInterface S" -- [Sharing Platform]
[Sharing Platform] - () "REST Interface S"
}
package "plugin" {
[Plugin Web Page] .. () "WebInterface P" : "(2) GET"
() "WebInterface P" -- [Plugin Application]
() "REST Interface P" - [Plugin Application]
}
[Sharing Web Page] ..> [Plugin Web Page]: "(1) invoke via actionTransferURL (+ BasketToken + further Parameters)"
()"REST Interface S" <.. [Plugin Application] : "(3) get action parameters"
```
Below you find a sketch of the basic process of the the invocation of a plugin action. The action is initiated by a browser-based forward to the plugin web page, that contains a token to identify the basket and the URI to call back the REST interface.
**Remark**: The process can also work completely without a web interface of the plugin. Then the actionTransferURL is just an invocation of an REST interface.
```plantuml
actor "User Browser"
== Initialization (and regular heart beat monitoring) ==
"Sharing Plattform" -> Connector : REST config URL
Connector --> "Sharing Plattform" : SharingPluginConfig
== Shopping Session ==
[-> "User Browser"** : start session
"User Browser"-> "Sharing Plattform" : fill shopping basket
"User Browser"-> "Sharing Plattform" : trigger Action
"Sharing Plattform" --> "User Browser": redirect to action.actionTransferURL + "/<basketToken>?" + "apiBaseURL="<apiBaseURL> + "&returnURL=..."
"User Browser"-> Connector : action.actionTransferURL + "/<basketToken>?" + ...
activate Connector
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>
"Sharing Plattform" --> Connector: ShoppingBasket
Connector -> Connector: evaluate Basket, do Work
activate Connector #DarkSalmon
Connector -> "Sharing Plattform": REST <apiBaseURL>/basket/<basketToken>/repository/<exerciseId>
"Sharing Plattform" --> Connector: Zipped repository (master, latest commit)
Connector --> "User Browser": Result (HTML, PDF, ..., further actions)
deactivate Connector
Connector --> "User Browser": Optional - redirect to <returnURL>
deactivate Connector
```
## REST interface provided by the sharing Plattform
You can find a description of the current API with Swagger-UI at https://search.sharing-codeability.uibk.ac.at/swagger-ui/index.html
The following REST services are provided: (**Remark**: https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1 is just an example REST url, this must be replaced by the _apiBaseURL_ submitted via the actionTransferURL.)
1. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket/ returns the Shopping Basket for this basketToken.
2. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/basket//repository/ returns the zipped content of the current master branch of the exercise repository. Please note, the content of the file currently contains the repository identically as the _download functionality_ in the git lab repository, but the (redundant) main folder is eliminated. I.e. when unzipping the layout is identical iff cloned directly from the repository (however the .git information is missing).
3. https://sharing.codeability.uibk.ac.at/api/pluginIF/v0.1/page-details gets a SearchRequestDTO and returns the corresponding SearchResultsDTO.
\ No newline at end of file