Course Subjects API. Used to look up courses in the class-search api.
Current implementations of the Dropwizard and JDK.
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 \
> --cacert doej.pem \
> --user "username:password" \
> https://localhost:8080/api/v0/
{"name":"subjects-api","time":1469755834914,"commit":"c2183c8","documentation":"swagger.yaml"}
NOTE: you should only specify a certificate with --cacert for local testing. Production servers should use a real certificate issued by a valid certificate authority.
This resource returns an array of objects representing the courses matching the search query:
$ curl \
--insecure \
--key doej.cer \
--user "username:password" \
https://localhost:8080/v1/subjects
{
"links": {},
"data": [
{
"id": "AC",
"type": "subjects",
"attributes": {
"abbreviation": "AC",
"title": "Agricultural Chemistry"
},
"links": null
},
{
"id": "AE",
"type": "subjects",
"attributes": {
"abbreviation": "AE",
"title": "Agricultural Engineering"
},
"links": null
},
...
]
}