Person Service
The following sections describe operations provided by the Person web service. The service supports both JSON and XML formats.
Operation createPerson
Creates a person in PO database.
HTTP Method | POST |
---|---|
URL | /person |
Request Body | XML/JSON Person |
Response Body | XML/JSON Person |
HTTP Response Code | Success: 201
Errors:
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request):
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): |
Operation updatePerson
Updates an existing person (for given ID) in PO database.
HTTP Method | PUT |
---|---|
URL | /person/{id} |
Request Body | XML/JSON Person |
Response Body | XML/JSON Person |
HTTP Response Code | Success:
|
Sample URL and Request Body | URL–> https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428 Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request): Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): |
Operation changePersonStatus
Changes the status of an existing person (for given ID).
HTTP Method | PUT |
---|---|
URL | /person/{id}/status |
Request Body | New status string (text/plain) |
Response Body | New status string (text/plain) |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428/status Request Header: Content-Type text/plain Accept text/plain Body: ACTIVE
|
Operation getPerson
Gets the person by its database ID.
HTTP Method | GET |
---|---|
URL | /person/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON Person |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428 Request Header (for JSON Request): Accept application/json Request Header (for XML Request): Accept application/xml |
Operation getPersonsByCTEPId
Gets the Persons for the given CTEP id.
HTTP Method | GET |
---|---|
URL | /person/ctep/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON Persons |
HTTP Response Code | Success: 200
Errors:
404. Not Found
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/ctep/24561 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml
|
Operation searchPersons
Searches the persons.
HTTP Method | GET |
---|---|
URL | /persons |
Request Body | N/A |
Response Body | XML/JSON PersonSearchResultList or empty collection if no person found matching the criteria. |
HTTP Response Code | Success: 200
Errors: 500. Internal Server Error
|
Sample URL and Request Body | Sample URLs: The URL can have one or more search criteria. The different search criteria are: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?affiliation=Cancer https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?CTEPID=25879 https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?id=28228758 https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?countryCode=USA Request Header (for JSON Request): Accept application/json Request Header (for XML Request): Accept application/xml |
Operation createPersonRole
Creates a personRole.
HTTP Method | POST |
---|---|
URL | /role |
Request Body | XML/JSON Person Role |
Response Body | XML/JSON Person Role |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request - HealthCareProvider): Note-> The body for ClinicalResearchStaff and OrganizationalContact will have respective @Class and other attributes. Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): 1) Sample request for Create OrganizationalContact: 2) Sample request for Create HealthCareProvider: |
Operation updatePersonRole
Updates an existing personRole for given type and id.
HTTP Method | PUT |
---|---|
URL | /role/{type}/{id} |
Request Body | XML/JSON Person Role |
Response Body | XML/JSON Person Role |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body | URL (for updating OrganizationalContact): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/OrganizationalContact/28210749 Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request - OrganizationalContact): URL (for updating ClinicalResearchStaff): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/ClinicalResearchStaff/28211370 URL (for updating HealthCareProvider): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/HealthCareProvider/28211370 Note-> The body for ClinicalResearchStaff and HealthCareProvider will have respective @Class and other attributes.
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request - HealthCareProvider): |
Operation changePersonRoleStatus
Changes the status of an existing personrole for given type and id.
HTTP Method | PUT |
---|---|
URL | /role/{type}/{id}/status |
Request Body | New status string (text/plain) |
Response Body | New status string (text/plain) |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body | URL (for changing OrganizationalContact status): Request Header: Content-Type text/plain Accept text/plain Body: INACTIVE URL (for changing HealthCareProvider status): |
Operation getPersonRolesByPersonId
Gets the personRoles for given person id.
HTTP Method | GET |
---|---|
URL | /person/{id}/roles |
Request Body | N/A |
Response Body | XML/JSON PersonRoles or empty collection if no roles for the person id |
HTTP Response Code | Success: 200 Response data: personRoleList element Description: List of personRole for given Person id. Errors:
|
Sample URL and Request Body | URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/269790/roles Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml
|
Operation getPersonRoleById
Gets the personRole for given role type and id.
HTTP Method | GET |
---|---|
URL | /role/{type}/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON PersonRole |
HTTP Response Code | Success: 200 Response data: personRole element Description: PersonRole details for the given personRole type and id. Errors:
|
Sample URL and Request Body | Sample URLs: For HealthCareProvider-> https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/HealthCareProvider/269797 For ClinicalResearchStaff: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/ClinicalResearchStaff/9558371 For OrganizationalContact: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/OrganizationalContact/9558371 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Organization Service
The following sections describe operations provided by the Organization web service.
Operation createOrganization
Creates an Organization in PO database.
HTTP Method | POST |
---|---|
URL | /organization |
Request Body | XML/JSON Organization |
Response Body | XML/JSON Organization |
HTTP Response Code | Success: HTTP Response : 201 Response data : organization element Description: Details of the created Organization, along with uri. Errors:
|
Sample URL and Request Body (XML Format) | URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request):
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): |
Operation updateOrganization
Updates an existing Organization for given organization id.
HTTP Method | PUT |
---|---|
URL | /organization/{id} |
Request Body | XML/JSON Organization |
Response Body | XML/JSON Organization |
HTTP Response Code | Success: 200
Errors:
NOTE : The updated organization name is added as an alias (not part of response). However a search will return this alias.
|
Sample URL and Request Body (XML Format) | URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/28227601 Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request):
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): |
Operation getOrganization
Gets the Organization on the basis of organization (database) id.
HTTP Method | GET |
---|---|
URL | /organization/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON Organization |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body (XML Format) | URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/28227567 Request Header (for JSON Request):
Accept application/json Request Header (for XML Request): Accept application/xml |
Operation searchOrganizations
Searches the Organizations.
HTTP Method | GET |
---|---|
URL | /organizations |
Request Body | N/A |
Response Body | Success: 200
Errors: 500. Internal Server Error
**Note
|
HTTP Response Code | Sample URLs: The URL can have one or more search criteria. The different search criteria are: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?id=140392 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Sample URL and Request Body (XML Format) | Sample URLs: The URL can have one or more search criteria. The different search criteria are: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?id=140392 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation createOrganizationRole
Creates an OrganizationRole.
HTTP Method | POST |
---|---|
URL | /role |
Request Body | XML/JSON OrganizationRole |
Response Body | XML/JSON OrganizationRole |
HTTP Response Code | Success: 201
Errors:
|
Sample URL and Request Body (XML Format) | URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request - HealthCareFacility):
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request): For creating a HealthCareFacility: For creating a OversightCommittee: |
Operation updateOrganizationRole
Updates an existing OrganizationRole (for given type and id).
HTTP Method | PUT |
---|---|
URL | /role/{type}/{id} |
Request Body | XML/JSON OrganizationRole |
Response Body | XML/JSON OrganizationRole |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body (XML Format) | URL for updating a HealthCareFacility–> Request Header (for JSON Request): Content-Type application/json Accept application/json Body (for JSON Request):
Request Header (for XML Request): Content-Type application/xml Accept application/xml Body (for XML Request)–> |
Operation changeOrganizationRoleStatus
Changes the status of an existing OrganizationRole (for given type and id).
HTTP Method | PUT |
---|---|
URL | /role/{type}/{id}/status |
Request Body | New status string (text/plain) |
Response Body | New status string (text/plain) |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body (XML Format) | URL for changing HealthCareFacility status: Request Header: Content-Type text/plain Accept text/plain Body: INACTIVE
URL for changing ResearchOrganization status: |
Operation getOrganizationRolesByOrgId
Gets the OrganizationRole for the given organization database id.
HTTP Method | GET |
---|---|
URL | /organization/{id}/roles |
Request Body | N/A |
Response Body | XML/JSON OrganizationRoles or empty collection if no roles for the organization |
HTTP Response Code | Success: 200
Errors:
|
Sample URL and Request Body (XML Format) | Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation getOrganizationRolesByCTEPId
Gets the OrganizationRoles for the given CTEP id.
HTTP Method | GET |
---|---|
URL | /organization/ctep/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON OrganizationRoles |
HTTP Response Code | Success: 200
Errors: 200
Errors:
|
Sample URL and Request Body (XML Format) | URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/ctep/11030 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation getOrganizationRoleById
Gets the OrganizationRole (for given organization role type and id).
HTTP Method | GET |
---|---|
URL | /role/{type}/{id} |
Request Body | N/A |
Response Body | Non-empty XML/JSON OrganizationRole |
HTTP Response Code | Success: 200
Errors: 200
Errors:
|
Sample URL and Request Body (XML Format) | Sample URLs: For HealthCareFacility: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/HealthCareFacility/7335 For ResearchOrganization: For OversightCommittee: Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Family Service
The following sections describe operations provided by the Family web service.
Operation searchFamilies
Searches the families on the basis of Family name and/or organizationId. If URL has both family name and organizationId, then the result will be the intersection of the two search results.
HTTP Method | GET |
---|---|
URL | /families |
Request Body | N/A |
Response Body | XML/JSON FamilyList or empty collection if no family found for the given name(if specified) or organizationId(if specified). or exception if organizationId is specified but no organization found of the given organizationId. |
HTTP Response Code | Success: HTTP Response : 200 Response data : familyList element Description: The list having family matching given search criteria. Errors:
|
Sample URL | Sample URLs–> https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families?name=cancer https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families?name=cancer&organizationId=149221 (both present in search criteria) https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families (search criteria blank) Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation getFamilyMemberRelationshipsByFamilyId
Gets the FamilyMemberRelationships on the basis of familyId.
HTTP Method | GET |
---|---|
URL | /familyMemberRelationships |
Request Body | N/A |
Response Body | XML/JSON FamilyMemberRelationshipList or empty collection if no familyMemberRelationship found for given familyId. or exception if family for the given familyId is not found in the database |
HTTP Response Code | Success: HTTP Response : 200 Response data : familyMemberRelationshipList element Description: The list having familyMemberRelationship matching given search criteria. Errors: 1. HTTP Response : 500 (Internal Server Error) Description : When an exception occurs at the backend(except EntityNotFoundException). Response Message: Error message in text/plain format. 2. HTTP Response : 404 (Not Found) Description : When the family for the given familyId is not found in the database. Response Message: Error message in text/plain format. |
Sample URL | Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation getFamily
Gets the Family by its ID.
HTTP Method | GET |
---|---|
URL | /family/{id} |
Request Body | N/A |
Response Body | Success: HTTP Response : 200 Response data : family element Description: Family for given ID 200
Errors:
|
HTTP Response Code | Success: HTTP Response : 200 Response data : family element Description: Family for given ID 200
Errors:
|
Sample URL | URL: https://trials.nci.nih.gov/po-webservices/services/family-rest-service/family/33217 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
Operation getFamilyMember
Gets the FamilyMember by its ID.
HTTP Method | GET |
---|---|
URL | /familymember/{id} |
Request Body | NA |
Response Body | Success: 200
Errors:
|
HTTP Response Code | Success: 200
Errors:
|
Sample URL | URL: https://trials.nci.nih.gov/po-webservices/services/family-rest-service/familymember/13334 Request Header (for JSON Request): Accept application/json
Request Header (for XML Request): Accept application/xml |
1 Comment
Frost, Ruth (NIH/NCI) [C]
At the time of release for CTRPMICRO-509, I archived the changeOrganizationStatus content.