1. Overview

Interface allowing north-bound, REST access to symbIoTe core services

1.1. Version information

Version : 3.0.0

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 : /

1.5. Tags

  • Core Interface Controller : Operations of Core Interface Controller

1.6. Produces

  • application/json

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
optional

Federation filter

string

Query

platformId
optional

Platform filter

string
Responses
HTTP Code Description Schema

200

OK

FederationGroupedPlatformMisdeedsReport

400

Received security request was malformed

No Content

401

Unauthorized Entry

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Internal Server Error

No Content

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
optional

Platform filter

string

Query

searchOriginPlatformId
optional

Search Origin Platform filter

string
Responses
HTTP Code Description Schema

200

OK

OriginPlatformGroupedPlatformMisdeedsReport

400

Received security request was malformed

No Content

401

Unauthorized Entry

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Internal Server Error

No Content

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
required

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
Consumes

  • application/json

2.1.4. Cleanup all consumed coupons before provided timestamp

POST /coreInterface/cleanup_coupons
Parameters
Type Name Description Schema

Body

timestamp
required

timestamp

string
Responses
HTTP Code Description Schema

200

OK

ResponseEntity

201

Created

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Consumes

  • application/json

2.1.5. Consume coupon in the Core BTM

POST /coreInterface/consume_coupon
Parameters
Type Name Description Schema

Header

x-auth-coupon
required

x-auth-coupon

string
Responses
HTTP Code Description Schema

200

OK

ResponseEntity

201

Created

No Content

400

Received coupon didn’t pass validation

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Consumes

  • application/json

2.1.6. List used coupons

POST /coreInterface/couponusage
Parameters
Type Name Description Schema

Body

filter
required

filter

string
Responses
HTTP Code Description Schema

200

OK

ResponseEntity

201

Created

No Content

400

Received request was malformed

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Consumes

  • application/json

2.1.7. Returns collection of available platforms (their AAMs and components)

GET /coreInterface/get_available_aams
Responses
HTTP Code Description Schema

200

OK

AvailableAAMsCollection

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Internal AAM Error

No Content

2.1.8. Get component certificate

GET /coreInterface/get_component_certificate/platform/{platformIdentifier}/component/{componentIdentifier}
Parameters
Type Name Description Schema

Path

componentIdentifier
required

Component identifier

string

Path

platformIdentifier
required

Platform identifier

string
Responses
HTTP Code Description Schema

200

The component certificate in PEM format

string

401

Unauthorized

No Content

403

Forbidden

No Content

404

Certificate could not be found

No Content

500

Could not retrieve Component Certificate

No Content

2.1.9. Issues a Guest Token

POST /coreInterface/get_guest_token
Responses
HTTP Code Description Schema

200

OK
Headers :
x-auth-token (string) : Guest Token.

string

201

Created

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Could not create Guest Token

No Content
Consumes

  • application/json

2.1.10. Issues a Home Token

POST /coreInterface/get_home_token
Parameters
Type Name Description Schema

Header

x-auth-token
required

Login request

string
Responses
HTTP Code Description Schema

200

OK
Headers :
x-auth-token (string) : Home Token.

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
Consumes

  • application/json

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

required to initialize user’s management operation

Credentials
Responses
HTTP Code Description Schema

200

OK

UserDetails

201

Created

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Internal User Management Error

No Content
Consumes

  • application/json

2.1.12. CouponEntity validation in Core BTM

POST /coreInterface/is_coupon_valid
Parameters
Type Name Description Schema

Header

x-auth-coupon
required

x-auth-coupon

string
Responses
HTTP Code Description Schema

200

OK

ResponseEntity

201

Created

No Content

400

Received coupon was malformed

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Consumes

  • application/json

2.1.13. Query for resources

GET /coreInterface/query
Description

Search for resources using defined query parameters

Parameters
Type Name Description Schema

Header

x-auth-*
required

each SecurityCredentials entry header, they are numbered 1..size

string

Header

x-auth-size
required

securityCredentials set size header

string

Header

x-auth-timestamp
required

timestamp of the request

string

Query

description
optional

description of a resource

string

Query

id
optional

ID of a resource

string

Query

locationLatitude
optional

latitude of resource’s location

number(double)

Query

locationLongitude
optional

longitude of resource’s location

number(double)

Query

locationName
optional

name of resource’s location

string

Query

location_lat
optional

latitude of resource’s location

number(double)

Query

location_long
optional

longitude of resource’s location

number(double)

Query

location_name
optional

name of resource’s location

string

Query

maxDistance
optional

maximum radius from specified latitude and longitude to look for resources

integer(int32)

Query

max_distance
optional

maximum radius from specified latitude and longitude to look for resources

integer(int32)

Query

name
optional

name of a resource

string

Query

observedProperty
optional

resource’s observed property; can be passed multiple times (acts as AND)

< string > array(multi)

Query

observedPropertyIri
optional

resource’s observed property by using full IRI; can be passed multiple times (acts as AND)

< string > array(multi)

Query

observed_property
optional

resource’s observed property; can be passed multiple times (acts as AND)

< string > array(multi)

Query

observed_property_iri
optional

resource’s observed property by using full IRI; can be passed multiple times (acts as AND)

< string > array(multi)

Query

owner
optional

owner of a platform that resource belongs to

string

Query

platformId
optional

ID of a platform that resource belongs to

string

Query

platformName
optional

name of a platform that resource belongs to

string

Query

platform_id
optional

ID of a platform that resource belongs to

string

Query

platform_name
optional

name of a platform that resource belongs to

string

Query

resourceType
optional

type of a resource

string

Query

resource_type
optional

type of a resource

string

Query

shouldRank
optional

whether results should be ranked

boolean

Query

should_rank
optional

whether results should be ranked

boolean
Responses
HTTP Code Description Schema

200

OK

QueryResponse

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Query execution error on server side

No Content

2.1.14. Register coupon in the Core BTM.

POST /coreInterface/register_coupon
Parameters
Type Name Description Schema

Header

x-auth-coupon
required

x-auth-coupon

string
Responses
HTTP Code Description Schema

200

OK

ResponseEntity

201

Created

No Content

400

Received coupon was malformed

No Content

401

Received coupon was not valid

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Internal server error occurred (DB error, connection error)

No Content
Consumes

  • application/json

2.1.15. Get resources' URLs

GET /coreInterface/resourceUrls
Description

Gets URLs of resources specified by passed IDs

Parameters
Type Name Description Schema

Header

x-auth-*
required

each SecurityCredentials entry header, they are numbered 1..size

string

Header

x-auth-size
required

securityCredentials set size header

string

Header

x-auth-timestamp
required

timestamp of the request

string

Query

id
required

Resource ID; can be passed multiple times to serve multiple resources at once

< string > array(multi)
Responses
HTTP Code Description Schema

200

Returns requested URLs in a form of {"id1":"url1","id2":"url2" … }

string

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Query execution error on server side

No Content

2.1.16. Allows users to revoke their client certificates and tokens

POST /coreInterface/revoke_credentials
Parameters
Type Name Description Schema

Body

Revocation Request
required

Depending on it’s fields, token or certificate can be revoked

RevocationRequest
Responses
HTTP Code Description Schema

200

OK

string

201

Created

No Content

400

Request contains invalid arguments

No Content

401

Incorrect credentials were provided

No Content

403

Client account is not activated or blocked

No Content

404

Not Found

No Content
Consumes

  • application/json

2.1.17. Allows signing certificates' requests

POST /coreInterface/sign_certificate_request
Parameters
Type Name Description Schema

Body

certificateRequest
required

Request required to sign a certificate for given (username, clientId) tupple

CertificateRequest
Responses
HTTP Code Description Schema

200

The certificate in PEM format

string

201

Created

No Content

401

Unauthorized

No Content

403

Client account is not activated or blocked

No Content

404

Not Found

No Content

500

Could not sign the requested certificate

No Content
Consumes

  • application/json

2.1.18. Sparql query for resources

POST /coreInterface/sparqlQuery
Description

Search for resources using sparql query

Parameters
Type Name Description Schema

Header

x-auth-*
required

each SecurityCredentials entry header, they are numbered 1..size

string

Header

x-auth-size
required

securityCredentials set size header

string

Header

x-auth-timestamp
required

timestamp of the request

string

Body

Sparql query
optional

Sparql query with desired response format

SparqlQueryRequest
Responses
HTTP Code Description Schema

200

OK

string

201

Created

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

500

Query execution error on server side

No Content
Consumes

  • application/json

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
optional

used for Offline scenarios

string

Header

x-auth-client-cert
optional

used for Offline scenarios

string

Header

x-auth-iss-cert
optional

used for Offline scenarios

string

Header

x-auth-token
required

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
Consumes

  • application/json

3. Definitions

3.1. AAM

Name Schema

aamAddress
optional

string

aamCACertificate
optional

Certificate

aamInstanceFriendlyName
optional

string

aamInstanceId
optional

string

componentCertificates
optional

< string, Certificate > map

siteLocalAddress
optional

string

3.2. AvailableAAMsCollection

Name Schema

availableAAMs
optional

< string, AAM > map

3.3. Capability

Name Schema

effects
optional

< Effect > array

name
optional

string

parameters
optional

< Parameter > array

3.4. Certificate

Name Schema

certificateString
optional

string

3.5. CertificateRequest

Name Schema

clientCSRinPEMFormat
optional

string

clientId
optional

string

password
optional

string

username
optional

string

3.6. Credentials

Name Schema

password
optional

string

username
optional

string

3.7. Datatype

Name Schema

array
optional

boolean

isArray
optional

boolean

3.8. Effect

Name Schema

actsOn
optional

FeatureOfInterest

affects
optional

< string > array

3.9. FailedFederationAuthorizationReport

Name Schema

federationId
optional

string

resourceId
optional

string

resourcePlatformId
optional

string

searchOriginPlatformId
optional

string

securityRequest
optional

SecurityRequest

3.10. FeatureOfInterest

Name Schema

description
optional

< string > array

hasProperty
optional

< string > array

name
optional

string

3.11. FederationGroupedPlatformMisdeedsReport

Name Schema

detailsByFederation
optional

< string, < string, integer(int32) > map > map

totalMisdeeds
optional

integer(int32)

3.12. Map«string,int»

Type : < string, Integer > map

3.13. OriginPlatformGroupedPlatformMisdeedsReport

Name Schema

detailsBySearchOriginPlatform
optional

< string, < string, integer(int32) > map > map

totalMisdeeds
optional

integer(int32)

3.14. Parameter

Name Schema

datatype
optional

Datatype

mandatory
optional

boolean

name
optional

string

restrictions
optional

< Restriction > array

3.15. Property

Name Schema

description
optional

< string > array

iri
optional

string

name
optional

string

3.16. QueryResourceResult

Name Schema

capabilities
optional

< Capability > array

description
optional

string

id
optional

string

inputParameters
optional

< Parameter > array

locationAltitude
optional

number(double)

locationLatitude
optional

number(double)

locationLongitude
optional

number(double)

locationName
optional

string

name
optional

string

observedProperties
optional

< Property > array

owner
optional

string

platformId
optional

string

platformName
optional

string

ranking
optional

number(float)

resourceType
optional

< string > array

3.17. QueryResponse

Name Schema

body
optional

< QueryResourceResult > array

message
optional

string

serviceResponse
optional

string

status
optional

integer(int32)

3.18. ResponseEntity

Name Schema

body
optional

object

statusCode
optional

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
optional

integer(int32)

3.19. Restriction

Type : object

3.20. RevocationRequest

Name Schema

certificateCommonName
optional

string

certificatePEMString
optional

string

couponString
optional

string

credentialType
optional

enum (USER, ADMIN, NULL)

credentials
optional

Credentials

foreignTokenString
optional

string

homeTokenString
optional

string

3.21. SecurityCredentials

Name Schema

authenticationChallenge
optional

string

clientCertificate
optional

string

clientCertificateSigningAAMCertificate
optional

string

foreignTokenIssuingAAMCertificate
optional

string

token
optional

string

3.22. SecurityRequest

Name Schema

proprietarySecurityPayload
optional

string

securityCredentials
required

< SecurityCredentials > array

timestamp
required

integer(int64)

3.23. SparqlQueryRequest

Name Schema

outputFormat
optional

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
optional

string

3.24. UserDetails

Name Schema

analyticsAndResearchConsent
optional

boolean

attributes
optional

< string, string > map

clients
optional

< string, Certificate > map

credentials
optional

Credentials

recoveryMail
optional

string

role
optional

enum (USER, SERVICE_OWNER, NULL)

serviceConsent
optional

boolean

status
optional

enum (NEW, ACTIVE, ACTIVITY_BLOCKED, CONSENT_BLOCKED)