Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Person

GET (Retrieve), POST (Create), PUT (Update), and DELETE individual Person records

GET: An individual Person record

Request

Code Block
text
text
GET /directory/person/123
HOST: www.sciencebase.gov
Accept: application/json

Response

Code Block
text
text
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
   "link":{
      "rel":"self",
      "url":"https://www.sciencebase.gov/directory/person/1193"
   },
   "id":1193,
   "name":"Sky Bristol/RGIO/USGS/DOI",
   "displayName":"Sky Bristol",
   "displayText":"Sky Bristol",
   "url":"https://my.usgs.gov/catalog/Global/catalogParty/show/1193",
   "email":"sbristol@usgs.gov",
   "description":"Sky Bristol currently manages the Applied Earth Systems Informatics Research branch in the Core Science Analytics and Synthesis program of the Core Science Systems Mission Area. He strives to develop innovative technology solutions for USGS science.",
   "richDescriptionHtml":"<p>\n\tSky Bristol currently manages the Applied Earth Systems Informatics Research branch in the Core Science Analytics and Synthesis program of the Core Science Systems Mission Area. He strives to develop innovative technology solutions for USGS science.<\/p>",
   "aliases":[
      {
         "id":4,
         "alias":"Bristol, RS",
         "annotation":"publishing alias"
      },
      {
         "id":1,
         "alias":"R. Sky Bristol",
         "annotation":"publishing alias"
      },
      {
         "id":2,
         "alias":"Robert Schuyler Bristol",
         "annotation":"full legal name"
      },
      {
         "id":3,
         "alias":"Bristol, R. Sky",
         "annotation":"publishing alias"
      }
   ],
   "active":true,
   "primaryLocation":{
      "id":1866,
      "name":"Sky Bristol/RGIO/USGS/DOI - Primary Location",
      "building":"DFC Bldg 810",
      "buildingCode":"KBT",
      "officePhone":"303-202-4181",
      "faxPhone":"303-202-4710",
      "mailAddress":{
         "line1":"Box 25046, Denver Federal Center, Mail Stop 306",
         "mailStopCode":"306",
         "city":"Denver",
         "state":"CO",
         "zip":"80225-0046",
         "country":"USA"
      },
      "streetAddress":{
         "line1":"West 6th Ave. & Kipling St., DFC Bldg. 810",
         "city":"Lakewood",
         "state":"CO",
         "zip":"80225-0046",
         "country":"US"
      },
      "longitude":-105.1247994,
      "latitude2":null
   },
   "partyLocations":[
      {
         "link":{
            "rel":"self",
            "href":"https://www.sciencebase.gov/directory/location/1866/get"
         },
         "locationId":1866,
         "displayName":"Sky Bristol/RGIO/USGS/DOI - Primary Location",
         "primary":true,
         "sort":1
      }
   ],
   "permissions":{
      "read":{
         "acl":[
            "PUBLIC"
         ]
      },
      "write":{
         "acl":[
            "USER:sbristol@usgs.gov",
            "ROLE:PlotDataAdmin",
            "ROLE:ScienceBase_DataAdmin"
         ]
      }
   },
   "firstName":"Sky",
   "lastName":"Bristol",
   "jobTitle":"Manager Applied Earth Systems Informatics Research",
   "cellPhone":"303-241-4122",
   "username":"sbristol@usgs.gov",
   "supervisorId":6715,
   "supervisorDisplayName":"Michael P McDermott/GIO/USGS/DOI",
   "supervisor":{
      "link":{
         "rel":"self",
         "href":"https://www.sciencebase.gov/directory/person/6715"
      },
      "id":6715,
      "displayText":"Michael P McDermott"
   },
   "organizationId":59505,
   "organization":{
      "link":{
         "rel":"self",
         "href":"https://www.sciencebase.gov/directory/organization/59505"
      },
      "id":59505,
      "displayText":"Applied Earth Systems Informatics Research"
   },
   "protectedFromLdap":false,
   "extensions":{
      "usgs":{
         "employeeId":49602,
         "notesName":"Sky Bristol/RGIO/USGS/DOI",
         "orgCode":"GGHIEJ3000",
         "buildingCode":"KBT"
      }
   }
}

TODO: should self links be to the instance class or just person regardless

Notes About GET and the Person data

  • 404 is returned when no matching records found for ID

POST: Create a New Person Record

Request

Code Block
text
text
POST /directory/person
HOST: www.sciencebase.gov
Content-Type: application/json
Accept: application/json

{
   "name":"John Doe/SomeOrg",
   "displayName":"John Doe",
   "firstName":"John",
   "lastName":"Doe",
   "email":"jdoe@someorg.org",
	....
}

Response

Code Block
text
text
HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8

{
   "name":"John Doe/SomeOrg",
   "displayName":"John Doe",
   "firstName":"John",
   "lastName":"Doe",
   "email":"jdoe@someorg.org",
	....
}

PUT: Update an Existing Person Record

Request

Code Block
text
text
PUT /directory/person/123
HOST: www.sciencebase.gov
Content-Type: application/json
Accept: application/json

{
   "name":"John Doe/SomeOrg",
   "displayName":"John Doe",
   "firstName":"John",
   "lastName":"Doe",
   "email":"jdoe@someorg.org",
	....
}

Response

Code Block
text
text
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
   "name":"John Doe/SomeOrg",
   "displayName":"John Doe",
   "firstName":"John",
   "lastName":"Doe",
   "email":"jdoe@someorg.org",
	....
}

DELETE: Remove a record

Request

Code Block
text
text
DELETE /directory/person/123
HOST: www.sciencebase.gov
Accept: application/json

Response

Code Block
text
text
HTTP/1.1 200 OK
application/json;charset=utf-8

(TODO: finalizes behavior/messages for deletes. Although the http status will be the most important result, we may need some messages in the body.)

 

Person Properties

ID

Unique identifier, an integer.  This is used in the URI to identify the record for GET, POST, PUT and DELETE.

Code Block
"id":123

Name

A unique name for the record.  This property is required for a Party.

Code Block
"name":"John Doe/DOI/USGS"

DisplayName

An optional label to display instead of the record name.

Code Block
"displayName": "John Doe"

DisplayText

A read-only property add for convenience.

Code Block
"displayText": "John Doe"

URL

A web address for a page about the party.

Code Block
"url": "http://example.gov/homePageOf/jdoe"

Email

Code Block
"email": "jdoe@usgs.gov"

Description

Code Block
"description": "The happy employee who works on stuff."

Rich Description HTML

Code Block
"richDescriptionHtml": "The <b>happy</b> employe who &ldquo;works&rdquo; on <i>stuff</i>."

Aliases

Code Block
aliases: 
[
	{
		id: 3,
		alias: "Doe, John",
		annotation: "publishing alias"
    },

	{
		id: 4,
		alias: "Doe, J",
		annotation: "publishing alias"
    }
]

Active

A boolean flag to indicate the record is active.

Code Block
"active": true

Primary Location

Code Block
primaryLocation: 
{
id: 1866,

name: "Sky Bristol/RGIO/USGS/DOI - Primary Location",

building: "DFC Bldg 810",

buildingCode: "KBT",

officePhone: "303-202-4181",

faxPhone: "303-202-4229",

mailAddress: {line1: "Box 25046, Denver Federal Center, Mail Stop 306",

mailStopCode: "306",

city: "Denver",

state: "CO",

zip: "80225-0046",

country: "USA"


},

streetAddress: {line1: "West 6th Ave. & Kipling St., DFC Bldg. 810",

city: "Lakewood",

state: "CO",

zip: "80225-0046",

country: "US"


},

latitude2: null


},


First Name

Code Block
"firstName": "John"

Last Name

Code Block
"lastName": "Doe"

Job Title

Code Block
"jobTitle": "Manager of Directors"

Cell Phone

Code Block
"cellPhone": "555-123-1234"

Username (myUSGS)

Code Block
"username": "jdoe@usgs.gov"

Supervisor ID

Code Block
"supervisorId": 321

Supervisor

Code Block
"supervisor": {
	link: {
		rel: "self",
		href: "https://beta.sciencebase.gov/directory/person/321
	}
	id: 321
    displayText: "Sue Jones"
}

Organization ID

Code Block
"organizationId": 678

Organization

Code Block
"organization": {
	link: {
		rel: "self",
		href: "https://beta.sciencebase.gov/directory/organization/678
	}
	id: 321
    displayText: "Some Org"
}

protectedFromLdap

A flag to disable updates from Active Directory

Code Block
"protectedFromLdap": false

Extensions

A collection of objects to extend the properties beyond the core Person attributes.  USGS people have a USGS extenstion for USGS specific attributes.

Code Block
"extensions": {
	usgs: {
		employeeId: 10101,
		notesName: "John Doe/RGIO/USGS/DOI",
		orgCode: "GGGGGG9999",
		buildingCode: "ABC"
 }
}