OSU Directory Web API.
HTTPS is required for Web APIs in development and production. Use keytool(1)
to generate public and private keys.
Generate key pair and keystore:
$ keytool \
-genkeypair \
-dname "CN=Jane Doe, OU=Enterprise Computing Services, O=Oregon State University, L=Corvallis, S=Oregon, C=US" \
-ext "san=dns:localhost,ip:127.0.0.1" \
-alias doej \
-keyalg RSA \
-keysize 2048 \
-sigalg SHA256withRSA \
-validity 365 \
-keystore doej.keystore
Export certificate to file:
$ keytool \
-exportcert \
-rfc \
-alias "doej" \
-keystore doej.keystore \
-file doej.pem
Import certificate into truststore:
$ keytool \
-importcert \
-alias "doej" \
-file doej.pem \
-keystore doej.truststore
This project uses the build automation tool Gradle. Use the Gradle Wrapper to download and install it automatically:
$ ./gradlew
The Gradle wrapper installs Gradle in the directory ~/.gradle
. To add it to your $PATH
, add the following line to ~/.bashrc
:
$ export PATH=$PATH:/home/user/.gradle/wrapper/dists/gradle-2.4-all/WRAPPER_GENERATED_HASH/gradle-2.4/bin
The changes will take effect once you restart the terminal or source ~/.bashrc
.
List all tasks runnable from root project:
$ gradle tasks
Generate IntelliJ IDEA project:
$ gradle idea
Open with File
-> Open Project
.
Copy configuration-example.yaml to configuration.yaml
. Modify as necessary, being careful to avoid committing sensitive data.
Build the project:
$ gradle build
JARs will be saved into the directory build/libs/
.
Run the project:
$ gradle run
Any code that contains intellectual property from a vendor should be stored in Github Enterprise instead of public Github. Make the name of the contrib repo in Github Enterprise follow this format using archivesBaseName in gradle.properties.
archivesBaseName-contrib
Set the value of getContribFiles to yes in gradle.properties.
getContribFiles=yes
Also set the value of contribCommit to the SHA1 of the desired commit to be used from the contrib repository.
contribCommit={SHA1}
Files in a Github Enterprise repo will be copied to this directory upon building the application.
gradle build
Contrib files are copied to:
/src/main/groovy/edu/oregonstate/mist/contrib/
Clone the skeleton:
$ git clone --origin skeleton [email protected]:osu-mist/web-api-skeleton.git my-api
$ cd my-api
Rename the webapiskeleton package and SkeletonApplication class:
$ git mv src/main/groovy/edu/oregonstate/mist/webapiskeleton src/main/groovy/edu/oregonstate/mist/myapi
$ vim src/main/groovy/edu/oregonstate/mist/myapi/SkeletonApplication.class
Update gradle.properties with your package name and main class.
Replace swagger.yaml with your own API specification.
Update configuration-example.yaml as appropriate for your application.
Update the resource examples at the end of this readme.
Add the skeleton as a remote:
$ git remote add skeleton [email protected]:osu-mist/web-api-skeleton.git
$ git fetch skeleton
Merge the skeleton into your codebase:
$ git checkout feature/abc-123-branch
$ git merge skeleton/master
...
$ git commit -v
Fetch updates from the skeleton:
$ git fetch skeleton
Merge the updates into your codebase as before. Note that changes to CodeNarc configuration may introduce build failures.
$ git checkout feature/abc-124-branch
$ git merge skeleton/master
...
$ git commit -v
The Web API definition is contained in the Swagger specification.
The following examples demonstrate the use of curl
to make authenticated HTTPS requests.
This resource returns build and runtime information:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/'
{"name":"directory-api","time":1451339045330,"commit":"eb7164a","documentation":"swagger.yaml"}
This resource returns an object representing the directory entity matching the osuuid:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/directory/51646559347'
{"links":null,"data":{"id":51646559347,"type":"directory","attributes":{"firstName":"Taylor","lastName":"Brown","fullName":"Brown, Taylor Alexander","primaryAffiliation":"Student","jobTitle":null,"department":"Computer Science","departmentMailingAddress":null,"homePhoneNumber":null,"homeAddress":null,"officePhoneNumber":null,"officeAddress":null,"faxNumber":null,"emailAddress":"[email protected]","username":"browtayl","osuuid":51646559347}}}
An error is returned if no directory entities match:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/directory/1234567890'
{"status":404,"developerMessage":"Not Found","userMessage":"Not Found","code":1404,"details":"http://example.com/errors/1404"}
This resource returns an array of objects representing the directory entities matching the search query:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/directory/?q=leebran%20browtayl'
[{"firstName":"Brandon","lastName":"Lee","fullName":"Lee, Brandon James","primaryAffiliation":"Student","jobTitle":null,"department":"Education","departmentMailingAddress":null,"homePhoneNumber":null,"homeAddress":null,"officePhoneNumber":null,"officeAddress":null,"faxNumber":null,"emailAddress":"[email protected]","username":"leebrand","osuuid":78313277887},{"firstName":"Taylor","lastName":"Brown","fullName":"Brown, Taylor Alexander","primaryAffiliation":"Student","jobTitle":null,"department":"Computer Science","departmentMailingAddress":null,"homePhoneNumber":null,"homeAddress":null,"officePhoneNumber":null,"officeAddress":null,"faxNumber":null,"emailAddress":"[email protected]","username":"browtayl","osuuid":51646559347},{"firstName":"Brandon","lastName":"Lee","fullName":"Lee, Brandon Michael","primaryAffiliation":"Student","jobTitle":null,"department":"Computer Science","departmentMailingAddress":null,"homePhoneNumber":null,"homeAddress":null,"officePhoneNumber":null,"officeAddress":null,"faxNumber":null,"emailAddress":"[email protected]","username":"leebran","osuuid":64979932965}]
Search terms match names, email addresses, and usernames. An empty array is returned if no directory entities match:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/directory/?q=foobar'
{"links":null,"data":[]}
An error is returned if the request is invalid:
$ curl \
--insecure \
--user "username:password" \
'https://localhost:8080/api/v1/directory/?q='
{"status":400,"developerMessage":"Missing query parameter.","userMessage":"Bad Request","code":1400,"details":"http://example.com/errors/1400"}