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
Show whitespace changes
Inline Side-by-side
Artemis-Connection/Connector-Interface.md
View page @ 87e90692
......@@ -3,20 +3,22 @@
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** 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.
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
......@@ -41,11 +43,11 @@ This plugin-URL is used to retrieve further json-encoded configuration data for
```
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_)
......@@ -77,7 +79,6 @@ 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
......@@ -125,7 +126,6 @@ SharingResultDTO --> UserProvidedMetadataDTO
```
- **SharingPluginConfig**: configuration data of the Plugin (Metadata like name, description, ...). Information, which exercise types are supported.
```plantuml
......@@ -146,7 +146,9 @@ class Action {
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.
......@@ -161,13 +163,10 @@ When the filter condition matches on an exercise, the user can invoke the respec
![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.
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" {
......@@ -185,8 +184,7 @@ package "plugin" {
()"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.
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.
......@@ -229,13 +227,8 @@ deactivate Connector
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.)
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).
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