Introduction
Resources
Profile
The Profile resource represents a set of attributes for a user, i.e. person using the AAP, or for a domain.
The user profile is generated automatically when the user signs up to the AAP (either local or federated account). The Profile resource is used to retrieve and update the set of attributes.
The domain profile can be created/edited by a domain manager and can be accessed by any domain member.
Getting the set of attributes of a given user
This is how to retrieve the attributes for a given user.
Example request
GET /users/usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4/profile HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
$ curl 'https://explore.api.aai.ebi.ac.uk/users/usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4/profile' -i \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http GET 'https://explore.api.aai.ebi.ac.uk/users/usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4/profile' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 343
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "ajay",
"email" : "ajay@alibaba.com"
}
}
Getting the set of attributes of the logged-in user
Example request
GET /my/profile HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
$ curl 'https://explore.api.aai.ebi.ac.uk/my/profile' -i \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http GET 'https://explore.api.aai.ebi.ac.uk/my/profile' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 343
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "ajay",
"email" : "ajay@alibaba.com"
}
}
Searching the users based on the given profile attribute
This is how to retrieve the users for a given profile attribute. Profile attribute key must be given in path param (email or name) and value must be given in query param (alice@example.com).
Authorisation
You must be a member of aap.profile.search
in order to be able to use this search.
Example request
Unresolved directive in profile.adoc - include::/builds/sd/aap/aap-profiles-api/build/generated-snippets/search_users_by_attribute/http-request.adoc[] Unresolved directive in profile.adoc - include::/builds/sd/aap/aap-profiles-api/build/generated-snippets/search_users_by_attribute/curl-request.adoc[] Unresolved directive in profile.adoc - include::/builds/sd/aap/aap-profiles-api/build/generated-snippets/search_users_by_attribute/httpie-request.adoc[] ==== Example response Unresolved directive in profile.adoc - include::/builds/sd/aap/aap-profiles-api/build/generated-snippets/search_users_by_attribute/http-response.adoc[]
Getting the set of attributes of a given domain
This is how to retrieve the attributes for a given domain.
Example request
GET /domains/dom-9c620e5b-1f8e-45c0-a0d1-1b6560302014/profile HTTP/1.1
Authorization: Bearer fakeToken
Content-Type: application/json;charset=UTF-8
Host: localhost:8080
$ curl 'http://localhost:8080/domains/dom-9c620e5b-1f8e-45c0-a0d1-1b6560302014/profile' -i \
-H 'Authorization: Bearer fakeToken' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http GET 'http://localhost:8080/domains/dom-9c620e5b-1f8e-45c0-a0d1-1b6560302014/profile' \
'Authorization:Bearer fakeToken' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:integration-test:0
Content-Type: application/json;charset=UTF-8
Content-Length: 259
{"reference":"prf-16bab742-a7fd-4ee5-8569-dcaa267bf897","domain":{"domainName":null,"domainDesc":null,"domainReference":"dom-9c620e5b-1f8e-45c0-a0d1-1b6560302014","users":[],"managers":[],"authority":"ROLE_null"},"attributes":{"car":"Volvo","fruit":"Banana"}}
Getting the set of attributes in a profile
This is how to retrieve the details of a profile, which includes the attributes.
Example request
GET /profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90 HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' -i \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http GET 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 343
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "ajay",
"email" : "ajay@alibaba.com"
}
}
Creating a user profile
Creates new profile
Example request
POST /profiles HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
{"user": {"userReference":"usr-9832620d-ec53-43a1-873d-94c05b9c0a44"}, "attributes": { "name":"White Rabbit", "email":"rabbit@example.com", "address":"Somewhere on campus" }}
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles' -i -X POST \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"user": {"userReference":"usr-9832620d-ec53-43a1-873d-94c05b9c0a44"}, "attributes": { "name":"White Rabbit", "email":"rabbit@example.com", "address":"Somewhere on campus" }}'
$ echo '{"user": {"userReference":"usr-9832620d-ec53-43a1-873d-94c05b9c0a44"}, "attributes": { "name":"White Rabbit", "email":"rabbit@example.com", "address":"Somewhere on campus" }}' | http POST 'https://explore.api.aai.ebi.ac.uk/profiles' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 392
{
"reference" : "prf-27fccfa1-11fe-40ca-ab26-d2896b8fac81",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-9832620d-ec53-43a1-873d-94c05b9c0a44",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "White Rabbit",
"email" : "rabbit@example.com",
"address" : "Somewhere on campus"
}
}
Creating a domain profile
Creates a profile for a domain.
Authorisation
You must be a manager of the domain in order to be able to create the profile for the domain.
Example request
POST /profiles HTTP/1.1
Authorization: Bearer fakeToken
Content-Type: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 228
{"domain": {"domainReference":"dom-b38d6175-61e8-4d40-98da-df9188d91c82"}, "attributes": { "cost_center":"ABC123", "address":"South Building, EMBL-EBI, Wellcome Genome Campus, Hinxton, Cambridgeshire, CB10 1SD" }}
$ curl 'http://localhost:8080/profiles' -i -X POST \
-H 'Authorization: Bearer fakeToken' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"domain": {"domainReference":"dom-b38d6175-61e8-4d40-98da-df9188d91c82"}, "attributes": { "cost_center":"ABC123", "address":"South Building, EMBL-EBI, Wellcome Genome Campus, Hinxton, Cambridgeshire, CB10 1SD" }}'
$ echo '{"domain": {"domainReference":"dom-b38d6175-61e8-4d40-98da-df9188d91c82"}, "attributes": { "cost_center":"ABC123", "address":"South Building, EMBL-EBI, Wellcome Genome Campus, Hinxton, Cambridgeshire, CB10 1SD" }}' | http POST 'http://localhost:8080/profiles' \
'Authorization:Bearer fakeToken' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:integration-test:0
Content-Type: application/json;charset=UTF-8
Content-Length: 347
{"reference":"prf-2dd1723f-bff4-4752-bc24-06e74911cca9","domain":{"domainName":null,"domainDesc":null,"domainReference":"dom-b38d6175-61e8-4d40-98da-df9188d91c82","users":[],"managers":[],"authority":"ROLE_null"},"attributes":{"cost_center":"ABC123","address":"South Building, EMBL-EBI, Wellcome Genome Campus, Hinxton, Cambridgeshire, CB10 1SD"}}
Creating a domain profile with validation
Creates a profile for a domain, and includes a schema. The attributes must match the schema. The validation also applies on subsequent editing of any attributes.
The schema is expected to be a json schema specifically Draft 04. It can be specified either inline, or as a URL.
We currently support properties of "type": "string"
and the
corresponding validation. We are planning
to support the other types soon.
Authorisation
You must be a manager of the domain in order to be able to create the profile for the domain.
Example request
POST /profiles HTTP/1.1
Authorization: Bearer fakeToken
Content-Type: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 622
{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "long enough"
}
}
$ curl 'http://localhost:8080/profiles' -i -X POST \
-H 'Authorization: Bearer fakeToken' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "long enough"
}
}'
$ echo '{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "long enough"
}
}' | http POST 'http://localhost:8080/profiles' \
'Authorization:Bearer fakeToken' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:integration-test:0
Content-Type: application/json;charset=UTF-8
Content-Length: 582
{"reference":"prf-468a6f7a-a8fc-4d4b-a0e1-78da0f13b290","domain":{"domainName":null,"domainDesc":null,"domainReference":"dom-dnfavt","users":[],"managers":[],"authority":"ROLE_null"},"schema":"{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}","attributes":{"address":"long enough"}}
Example request - invalid attributes
POST /profiles HTTP/1.1
Authorization: Bearer fakeToken
Content-Type: application/json;charset=UTF-8
Host: localhost:8080
Content-Length: 656
{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "short",
"name" : "invalid cos has 9 in it"
}
}
$ curl 'http://localhost:8080/profiles' -i -X POST \
-H 'Authorization: Bearer fakeToken' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "short",
"name" : "invalid cos has 9 in it"
}
}'
$ echo '{
"reference" : null,
"domain" : {
"domainName" : null,
"domainDesc" : null,
"domainReference" : "dom-dnfavt",
"users" : [ ],
"managers" : [ ],
"authority" : "ROLE_null"
},
"schema" : "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"title\":\"Simple Schema\",\"description\":\"Example of attribute validation\",\"type\":\"object\",\"properties\":{\"address\":{\"description\":\"Where the person works\",\"type\":\"string\",\"minLength\":7},\"name\":{\"type\":\"string\",\"pattern\":\"^[^9]$\"}},\"required\":[\"address\"]}",
"attributes" : {
"address" : "short",
"name" : "invalid cos has 9 in it"
}
}' | http POST 'http://localhost:8080/profiles' \
'Authorization:Bearer fakeToken' \
'Content-Type:application/json;charset=UTF-8'
Example response - invalid attributes
HTTP/1.1 422 Unprocessable Entity
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Application-Context: application:integration-test:0
Content-Type: application/json;charset=UTF-8
Content-Length: 291
{"timestamp":"2022.09.07.15.45.21","status":"UNPROCESSABLE_ENTITY","message":"Data does not conform to Simple Schema. There are 2 error(s).","path":"http://localhost:8080/profiles","details":["$.address: must be at least 7 characters long","$.name: does not match the regex pattern ^[^9]$"]}
Updating a profile
This is how to modify a profile, as a whole
Example request
PUT /profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90 HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
{"name":"Foo", "email": "foo@foo.com" }
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' -i -X PUT \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"name":"Foo", "email": "foo@foo.com" }'
$ echo '{"name":"Foo", "email": "foo@foo.com" }' | http PUT 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 337
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "Foo",
"email" : "foo@foo.com"
}
}
Attribute
The Attribute resource represents a key/value pair of information. It is used to read / update / delete individual items of information.
Adding attributes to a profile
This is how to partially a profile, by adding/updating attributes so that the existing list is merged with the list in the request:
-
attributes in the request and in the profile are updated
-
attributes in the request and not in the profile are added
-
attributes not in the request and in the profile are left unchanged
Example request
PATCH /profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90 HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
{"name":"Foo"}
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' -i -X PATCH \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"name":"Foo"}'
$ echo '{"name":"Foo"}' | http PATCH 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 342
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"name" : "Foo",
"email" : "ajay@alibaba.com"
}
}
Getting a single attribute
This is how to retrieve an attribute in a profile.
Example request
GET /profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/email HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/email' -i \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http GET 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/email' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 16
ajay@alibaba.com
Deleting an attributes
This is how to remove an attribute from a profile.
Example request
DELETE /profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/name HTTP/1.1
Authorization: Bearer eyJhb...h7HgQ
Content-Type: application/json;charset=UTF-8
Host: explore.api.aai.ebi.ac.uk
$ curl 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/name' -i -X DELETE \
-H 'Authorization: Bearer eyJhb...h7HgQ' \
-H 'Content-Type: application/json;charset=UTF-8'
$ http DELETE 'https://explore.api.aai.ebi.ac.uk/profiles/prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90/name' \
'Authorization:Bearer eyJhb...h7HgQ' \
'Content-Type:application/json;charset=UTF-8'
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 322
{
"reference" : "prf-6b3c0b7d-1530-445a-859a-94c05b9c0a90",
"user" : {
"userName" : null,
"email" : null,
"userReference" : "usr-e8c1d6d5-6bf4-4636-a70e-41b8f32c70b4",
"fullName" : null,
"domains" : null,
"accountNonLocked" : false
},
"attributes" : {
"email" : "ajay@alibaba.com"
}
}