1. Overview
Interface allowing north-bound, REST access to symbIoTe core services
1.2. Contact information
Contact : Artur Jaworski
Contact Email : artur.jaworski@man.poznan.pl
1.3. License information
License : GNU Lesser General Public License v3.0
License URL : https://github.com/symbiote-h2020/CoreInterface/blob/master/LICENSE.txt
Terms of service : null
1.4. URI scheme
Host : https://symbiote-open.man.poznan.pl
BasePath : /
2. Resources
2.1. Core Interface Controller
Operations of Core Interface Controller
2.1.1. Returns information about platforms misdeeds, grouped by federations
GET /coreInterface/adm/federated_misdeeds/byFederation
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
federationId |
Federation filter |
string |
Query |
platformId |
Platform filter |
string |
2.1.2. Returns information about platforms misdeeds, grouped by search origin platforms
GET /coreInterface/adm/federated_misdeeds/bySearchOriginPlatform
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
platformId |
Platform filter |
string |
Query |
searchOriginPlatformId |
Search Origin Platform filter |
string |
2.1.3. Handles received reports of failed authorization within the federation
POST /coreInterface/adm/log_failed_federation_authorization
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
FailedFederationAuthorizationReport |
failedFederationAuthorizationReport |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Report was correctly verified and saved. |
enum (100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509, 510, 511) |
201 |
Created |
No Content |
400 |
Received report is not correctly built. |
No Content |
401 |
Received security request doesn’t provide access to reported resource. |
No Content |
403 |
Forbidden |
No Content |
404 |
Some of the reported entities are unrecognized. |
No Content |
500 |
Internal Server Error. |
No Content |
2.1.4. Cleanup all consumed coupons before provided timestamp
POST /coreInterface/cleanup_coupons
2.1.5. Consume coupon in the Core BTM
POST /coreInterface/consume_coupon
2.1.6. List used coupons
POST /coreInterface/couponusage
2.1.7. Returns collection of available platforms (their AAMs and components)
GET /coreInterface/get_available_aams
2.1.8. Get component certificate
GET /coreInterface/get_component_certificate/platform/{platformIdentifier}/component/{componentIdentifier}
2.1.9. Issues a Guest Token
POST /coreInterface/get_guest_token
2.1.10. Issues a Home Token
POST /coreInterface/get_home_token
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
string |
201 |
Created |
No Content |
400 |
Received token was malformed |
No Content |
401 |
Incorrect Credentials were provided |
No Content |
403 |
Client account is not activated or blocked |
No Content |
404 |
Not Found |
No Content |
500 |
Server failed to create Home Token |
No Content |
2.1.11. Performs management action based on management request
POST /coreInterface/get_user_details
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
User Management Request |
required to initialize user’s management operation |
2.1.12. CouponEntity validation in Core BTM
POST /coreInterface/is_coupon_valid
2.1.13. Query for resources
GET /coreInterface/query
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Header |
x-auth-* |
each SecurityCredentials entry header, they are numbered 1..size |
string |
Header |
x-auth-size |
securityCredentials set size header |
string |
Header |
x-auth-timestamp |
timestamp of the request |
string |
Query |
description |
description of a resource |
string |
Query |
id |
ID of a resource |
string |
Query |
locationLatitude |
latitude of resource’s location |
number(double) |
Query |
locationLongitude |
longitude of resource’s location |
number(double) |
Query |
locationName |
name of resource’s location |
string |
Query |
location_lat |
latitude of resource’s location |
number(double) |
Query |
location_long |
longitude of resource’s location |
number(double) |
Query |
location_name |
name of resource’s location |
string |
Query |
maxDistance |
maximum radius from specified latitude and longitude to look for resources |
integer(int32) |
Query |
max_distance |
maximum radius from specified latitude and longitude to look for resources |
integer(int32) |
Query |
name |
name of a resource |
string |
Query |
observedProperty |
resource’s observed property; can be passed multiple times (acts as AND) |
< string > array(multi) |
Query |
observedPropertyIri |
resource’s observed property by using full IRI; can be passed multiple times (acts as AND) |
< string > array(multi) |
Query |
observed_property |
resource’s observed property; can be passed multiple times (acts as AND) |
< string > array(multi) |
Query |
observed_property_iri |
resource’s observed property by using full IRI; can be passed multiple times (acts as AND) |
< string > array(multi) |
Query |
owner |
owner of a platform that resource belongs to |
string |
Query |
platformId |
ID of a platform that resource belongs to |
string |
Query |
platformName |
name of a platform that resource belongs to |
string |
Query |
platform_id |
ID of a platform that resource belongs to |
string |
Query |
platform_name |
name of a platform that resource belongs to |
string |
Query |
resourceType |
type of a resource |
string |
Query |
resource_type |
type of a resource |
string |
Query |
shouldRank |
whether results should be ranked |
boolean |
Query |
should_rank |
whether results should be ranked |
boolean |
2.1.14. Register coupon in the Core BTM.
POST /coreInterface/register_coupon
2.1.15. Get resources' URLs
GET /coreInterface/resourceUrls
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Header |
x-auth-* |
each SecurityCredentials entry header, they are numbered 1..size |
string |
Header |
x-auth-size |
securityCredentials set size header |
string |
Header |
x-auth-timestamp |
timestamp of the request |
string |
Query |
id |
Resource ID; can be passed multiple times to serve multiple resources at once |
< string > array(multi) |
2.1.16. Allows users to revoke their client certificates and tokens
POST /coreInterface/revoke_credentials
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
Revocation Request |
Depending on it’s fields, token or certificate can be revoked |
2.1.17. Allows signing certificates' requests
POST /coreInterface/sign_certificate_request
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
certificateRequest |
Request required to sign a certificate for given (username, clientId) tupple |
2.1.18. Sparql query for resources
POST /coreInterface/sparqlQuery
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Header |
x-auth-* |
each SecurityCredentials entry header, they are numbered 1..size |
string |
Header |
x-auth-size |
securityCredentials set size header |
string |
Header |
x-auth-timestamp |
timestamp of the request |
string |
Body |
Sparql query |
Sparql query with desired response format |
2.1.19. Responds with validation status of processed Validation request
POST /coreInterface/validate_credentials
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Header |
x-auth-aam-cert |
used for Offline scenarios |
string |
Header |
x-auth-client-cert |
used for Offline scenarios |
string |
Header |
x-auth-iss-cert |
used for Offline scenarios |
string |
Header |
x-auth-token |
Token to be validated |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
enum (VALID, EXPIRED_ISSUER_CERTIFICATE, EXPIRED_SUBJECT_CERTIFICATE, EXPIRED_TOKEN, REVOKED_IPK, REVOKED_SPK, REVOKED_TOKEN, WRONG_AAM, INVALID_TRUST_CHAIN, UNKNOWN, ISSUING_AAM_UNREACHABLE, NULL) |
201 |
Created |
No Content |
401 |
Unauthorized |
No Content |
403 |
Forbidden |
No Content |
404 |
Not Found |
No Content |
500 |
Error on server side |
No Content |
3. Definitions
3.1. AAM
Name | Schema |
---|---|
aamAddress |
string |
aamCACertificate |
|
aamInstanceFriendlyName |
string |
aamInstanceId |
string |
componentCertificates |
< string, Certificate > map |
siteLocalAddress |
string |
3.2. AvailableAAMsCollection
Name | Schema |
---|---|
availableAAMs |
< string, AAM > map |
3.3. Capability
Name | Schema |
---|---|
effects |
< Effect > array |
name |
string |
parameters |
< Parameter > array |
3.5. CertificateRequest
Name | Schema |
---|---|
clientCSRinPEMFormat |
string |
clientId |
string |
password |
string |
username |
string |
3.9. FailedFederationAuthorizationReport
Name | Schema |
---|---|
federationId |
string |
resourceId |
string |
resourcePlatformId |
string |
searchOriginPlatformId |
string |
securityRequest |
3.10. FeatureOfInterest
Name | Schema |
---|---|
description |
< string > array |
hasProperty |
< string > array |
name |
string |
3.11. FederationGroupedPlatformMisdeedsReport
Name | Schema |
---|---|
detailsByFederation |
< string, < string, integer(int32) > map > map |
totalMisdeeds |
integer(int32) |
3.12. Map«string,int»
Type : < string, Integer > map
3.13. OriginPlatformGroupedPlatformMisdeedsReport
Name | Schema |
---|---|
detailsBySearchOriginPlatform |
< string, < string, integer(int32) > map > map |
totalMisdeeds |
integer(int32) |
3.14. Parameter
Name | Schema |
---|---|
datatype |
|
mandatory |
boolean |
name |
string |
restrictions |
< Restriction > array |
3.15. Property
Name | Schema |
---|---|
description |
< string > array |
iri |
string |
name |
string |
3.16. QueryResourceResult
Name | Schema |
---|---|
capabilities |
< Capability > array |
description |
string |
id |
string |
inputParameters |
< Parameter > array |
locationAltitude |
number(double) |
locationLatitude |
number(double) |
locationLongitude |
number(double) |
locationName |
string |
name |
string |
observedProperties |
< Property > array |
owner |
string |
platformId |
string |
platformName |
string |
ranking |
number(float) |
resourceType |
< string > array |
3.17. QueryResponse
Name | Schema |
---|---|
body |
< QueryResourceResult > array |
message |
string |
serviceResponse |
string |
status |
integer(int32) |
3.18. ResponseEntity
Name | Schema |
---|---|
body |
object |
statusCode |
enum (100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509, 510, 511) |
statusCodeValue |
integer(int32) |
3.20. RevocationRequest
Name | Schema |
---|---|
certificateCommonName |
string |
certificatePEMString |
string |
couponString |
string |
credentialType |
enum (USER, ADMIN, NULL) |
credentials |
|
foreignTokenString |
string |
homeTokenString |
string |
3.21. SecurityCredentials
Name | Schema |
---|---|
authenticationChallenge |
string |
clientCertificate |
string |
clientCertificateSigningAAMCertificate |
string |
foreignTokenIssuingAAMCertificate |
string |
token |
string |
3.22. SecurityRequest
Name | Schema |
---|---|
proprietarySecurityPayload |
string |
securityCredentials |
< SecurityCredentials > array |
timestamp |
integer(int64) |
3.23. SparqlQueryRequest
Name | Schema |
---|---|
outputFormat |
enum (SRX, XML, JSON, SRJ, SRT, THRIFT, SSE, CSV, TSV, SRB, TEXT, COUNT, TUPLES, NONE, RDF, RDF_N3, RDF_XML, N3, TTL, TURTLE, GRAPH, NT, N_TRIPLES, TRIG) |
sparqlQuery |
string |
3.24. UserDetails
Name | Schema |
---|---|
analyticsAndResearchConsent |
boolean |
attributes |
< string, string > map |
clients |
< string, Certificate > map |
credentials |
|
recoveryMail |
string |
role |
enum (USER, SERVICE_OWNER, NULL) |
serviceConsent |
boolean |
status |
enum (NEW, ACTIVE, ACTIVITY_BLOCKED, CONSENT_BLOCKED) |