Child pages
  • NYU IT Directory API v1
Skip to end of metadata
Go to start of metadata

Overview

The NYU ITS Directory API provides a RESTful API to data in the NYU Public Directory. This API is based on the CIFER Registry Extraction API (which in turn is based on SCIM), and is currently configured to provide access to faculty and staff records. This API is still under development, and as such is subject to change or discontinuation without notice.

This API provides two interfaces: one to provide a detailed person record based on a NetID, and the other to search records based on role and/or a subset of family (last) name.

Servers

The Directory API is available on the following servers:

  • Prod: isapi.home.nyu.edu
  • Test/QA: qaisapi.home.nyu.edu

Authentication

The Directory API uses Basic Auth over HTTPS for authentication. For access, a Special-Purpose NetID and appropriate authorization are required.

Query For NetID

To obtain attributes for a specific NetID, issue a GET request to this endpoint:

https://SERVER/v1/people/network:NETID

replacing NETID with the NYU NetID you wish to query for. The response will be one of:

  • 200 OK: Record found. Response is a JSON object consisting of attribute/value pairs, with possible attributes defined below.

  • 400 Bad Request: There was an error in your request. The response may contain a JSON object with an error attribute explaining what went wrong. Fix your request before trying again.

  • 401 Unauthorized: The provided username and password are not valid.

  • 404 Not Found: NetID does not exist, or is associated with a record that is not public.

    • (warning) To distinguish 404 from the API indicating NetID does not exist vs 404 from the web server indicating a server configuration error, examine the message body in the response. An API error will include a JSON payload of the form {"error": "NETID not found"}.

  • 500 Internal Server Error: There is a problem with the server. The response may contain a JSON object with an error attribute explaining what went wrong. Try again later, or report the error for further assistance.

Example

 

Search By Affiliation/Name

 

To search by affiliation and/or name, issue a GET request to this endpoint:

https://SERVER/v1/people?filter=roles.affiliation eq "affiliate"

https://SERVER/v1/people?filter=name.family sw "x"

https://SERVER/v1/people?filter=roles.affiliation eq "employee" and name.family sw "x"

replacing AFFIL with either faculty or staff, and X with the initial letter or letters you wish to search for.
 

Important

You must properly encode the URL. i.e., spaces must be sent as %20, the quotes must be sent as %22, etc. Use the appropriate function from your programming environment to perform this encoding.

It is possible to paginate the entire result set by omitting the filter parameter. However, this is not supported when the LDAP backend is in use.


The response will be one of:

  • 200 OK: Record(s) found. Response is a JSON object consisting of an attribute totalResults that indicates the total number of results found, and Resources, that is a list of matching records, each in the same form as Query For NetID, above.

  • 400 Bad Request: There was an error in your request. The response may contain a JSON object with an error attribute explaining what went wrong. Fix your request before trying again.

  • 401 Unauthorized: The provided username and password are not valid.

  • 500 Internal Server Error: There is a problem with the server. The response may contain a JSON object with an error attribute explaining what went wrong. Try again later, or report the error for further assistance.

Pagination

Search results are paginated, by default returning 100 records at a time. The response metadata will indicate where in the pagination the response records are, though keep in mind result sets can change between calls. That is, there is no guarantee that records 1-100 or 101-200 will be the same sets each time. Furthermore, due to filtering of non-releasable records, the requested count of records may not be returned for each page.

Response metadata attributes are:

  • itemsPerPage: The number of records returned in the response, default 100.
  • startIndex: The index of the first result in the response, 1 based.
  • totalResults: The total number of records matching the query.

Pagination is controlled by request parameters appended to the query string. Supported request parameters are:

  • count: The number of records per page to return, may not exceed 100. Set to 0 to get a count only and no actual results.
  • startIndex: The index of the first record to return.

Example

 

Attributes

Each result consists of zero or more Person Level Attributes, and zero or more Role Level Attributes. A person with more than one affiliation with the University, such as President Hamilton who is both President of the University as well as a Professor of Chemistry, have one set of Role Level Attributes for each affiliation.

Not all attributes are present in all records.

Attribute Release Policies

 Each person record, role, and individual attribute is subject to an Attribute Release Policy. These policies, from most to least restrictive, are:

  • none: The attribute/role/person may not be released. Currently, the API does not return such attributes
  • internal: The attribute/role/person may be used internally within NYU only.
  • public: The attribute/role/person may be generally used.

Additional policies may be added in the future.

For restrictive policies, the broadest restricting policy must be applied. For example, if the entire person record is flagged as internal, then all attributes are to be treated as internal, regardless of how they are flagged. However, if the person record is flagged as public but a role is flagged as internal, then only that role (and its attributes) must be treated as internal.

Person Level Attributes

 
  • meta 

    • Description: Meta data applicable to the person

    • Multi-valued: No

    • Type: Complex, with these sub-attributes

      • release: Release policy for the Person, or for single-valued Person level attributes. Key/value pairs where key is the person level attribute the policy applies to, or * to indicate the entire Person record, and value is the appropriate release policy.

  • emailAddresses

    • Description: A list of email addresses associated with the person

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • address: The email address

      • release: Release policy for this email address

      • type

        • official: NYU email address

  • identifiers

    • Description: A list of identifiers associated with the person

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • identifier: The identifier

      • release: Release policy for this identifier

      • type

        • enterprise: NYU University ID (N#)

        • network: NYU NetID

  • names

    • Description: A list of names associated with the person

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • family: Family/last name

      • middle: Middle name(s)

      • given: First/given name

      • formatted: Complete name (given+family)

      • language: Language encoding of name, currently always en

      • release: Release policy for this name

      • type

        • official: Official name according to NYU data sources

        • preferred: Preferred name as set via self service

  • primaryAffiliation

    • Description: Primary affiliation with the University

    • Multi-valued: No

    • Type: One of employee, faculty, student

  • primaryCampus

    • Description: Primary campus

    • Multi-valued: No

    • Type: String, eg: New York

  • primarySubaffiliation 

    • Description: Subaffiliation associated the primaryAffiliation

    • Multi-valued: No

    • Type: Value corresponding to role record employeeType

    • (warning) This attribute is not part of the CIFER Core Schema

  • telephoneNumbers

    • Description: A list of telephone numbers associated with the person (note: there can also be telephone numbers associated with each role)

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • number: The telephone number

      • release: Release policy for this telephone number

      • type

        • preferred: Preferred telephone number as set via self service

  • urls

    • Description: A list of URLs associated with the person

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • url: The URL

      • release: Release policy for this URL

      • type

        • official: Official URL as set via self service

        • personal: Personal URL as set via self service

        • other: Other URL as set via self service

Role Level Attributes

  • meta

    • Description: Meta data applicable to the role

    • Multi-valued: No

    • Type: Complex, with these sub-attributes

      • id: Role record ID, primarily for internal use and should not be relied on

      • sor: System of Record asserting the original role attributes

      • release: Release policy for the Role, or for single-valued Role level attributes. Key/value pairs where key is the role level attribute the policy applies to, or * to indicate the entire Role record, and value is the appropriate release policy.

  • addresses

    • Description: A list of addresses associated with this role

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • country: Country

      • formatted: Complete address (may contain newlines)

      • locality: Locality (City)

      • postalCode: Postal/Zip code

      • region: Region (State)

      • room: Room number

      • street: Street

      • release: Release policy for this address

      • type

        • official: Office address

  • affiliation

    • Description: This role's affiliation with the University

    • Multi-valued: No

    • Type: One of alumniaffiliateemployee, student

  • classYear

    • Description: Graduation year for degree associated with this role

    • Multi-valued: No

    • Type: Integer

  • degree

    • Description: Degree for this role (eg: BS, MBA, etc)

    • Multi-valued: No

    • Type: String

  • department

    • Description: Department for this role

    • Multi-valued: No

    • Type: String

  • employeeType

    • (warning) This attribute is subject to change in a future update

    • Description: This role's subaffiliation; In spite of the attribute name, this includes subaffiliations for students as well as employees

    • Multi-valued: No

    • Type: String, eg facultyresearchercontractornondegree, etc

  • majors

    • Description: The primary major, secondary major, and minor for this role (where known)

    • Multi-valued: Yes, but no more than one entry per type (primary, secondary, minor)
    • Type: Complex, with these sub-attributes:
      • major: The department associated with the major
      • type
        • minor: Entry is for the minor associated with the degree
        • primary: Entry is for the primary major associated with the degree
        • secondary: Entry is for the secondary major associated with the degree
  • organization

    • Description: NYU Division / organization for this role

    • Multi-valued: No

    • Type: String

  • rankSor

    • Description: Where multiple role records are provided by the same SOR, the ranking of this role relative to the other roles for the same SOR (as determined by the SOR)

    • Multi-valued: No

    • Type: Integer

  • status

    • Description: Status for this role

    • Multi-valued: No

    • Type: One of currentrecentformer

  • telephoneNumbers

    • Description: A list of telephone numbers associated with this role

    • Multi-valued: Yes

    • Type: Complex, with these sub-attributes:

      • number: The telephone number

      • release: Release policy for this telephone number

      • type

        • fax: Fax number

        • office: Office number

  • title

    • Description: Title for this role

    • Multi-valued: No

    • Type: String

 

Sample Searches Using Curl

Samples using the Directory API with special-purpose NetID nyu4225 (for which a password is required).


Search for a specific NetID:

$ curl -u nyu4225 'https://dirapi.home.nyu.edu/v1/people/network:ah170'

Obtain first 10 records where last name starts with 'tes'.  Verbose and with output to a file.
$ curl -o /tmp/curl.out -v -u nyu4225 'https://dirapi.home.nyu.edu/v1/people?filter=name.family%20sw%20%22tes%22&count=10'

 Just obtain the first 10 records where lastname starts with "tes"

$ curl -o /tmp/2.out -u nyu4225 'https://dirapi.home.nyu.edu/v1/people?filter=name.family%20sw%20%22tes%22&count=2'

Get the next 3 records:
Lastname search (5th record of searching names staring with sw):

 

NetID search:

 

 

 

 

 

 

 

 

 


  • No labels