This repository holds shared library for topcoder platform's V3 API and authentication using Dropwizard framework.
There are 2 core projects in this repository.
Use "dev" branch to parse and include for the latest code.
- tech.core.api -- Holds shared library for other teams to use for V3 API and Authentication scheme.
- tech.core.sample.dropwizard -- A sample dropwizard project showing how to use shared library.
- tech.core.service.identity -- Identity micro service components. There is no need to build or run this project as library and sample is all you need to include for other teams.
See "Core Service: Development Environment Setup" document (https://docs.google.com/a/topcoder.com/document/d/1e2aGnbXZgHvXZQ2GbGYksN8n0jiWxKRMbzaNc2QZBuA/edit#heading=h.ug5qzkdm27d6)
There is also Jenkins automatic build running for Sample project to test out quickly in dev environment. Goto
http://api.topcoder-dev.com/pub/index.html
API shared library have 2 goals in mind.
- Provide methods and wrapper objects to simplify the resource(interface) development to match V3 API protocol defined in this doc (https://docs.google.com/a/topcoder.com/presentation/d/15pucEI0MHj9y778EyaAWGh4MBH-I73i1-GS0ir7FhxE/edit)
- Provide authentication library to hook with Jersey injection (dropwizard @Auth)
- Other micro services should have ability to override or ignore the usage of shared library, in case of edge case scenario. In this case, each micro services will need to implement their own V3 protocol handling methods.
Topcoder platform uses Maven and custom repository (in Jenkins server) to hold our libraries and programs. Application should have following items on each of their pom files.
Include following to register our maven repository.
<repositories>
<repository>
<id>Topcoder Technology Maven Repository</id>
<url>http://maven.topcoder.net:8080/</url>
<snapshots>
<updatePolicy>always</updatePolicy>
</snapshots>
<releases>
<updatePolicy>always</updatePolicy>
</releases>
</repository>
</repositories>
Shared library will be included using following dependency.
<dependencies>
<dependency>
<groupId>com.topcoder.core.api</groupId>
<artifactId>tech.core.api</artifactId>
<version>API-3.0.0.8-SNAPSHOT</version>
</dependency>
</dependencies>
The basic usage of shared library is explained in this section. All terminology (like representation, resource, etc. follows dropwizard)
Representation class should be simple POJO class. The default fields that V3 pojo should have are defined in com.topcoder.core.api.v3.model.AbstractIdResource Extend this class for representation where necessary.
import com.topcoder.core.api.v3.model.AbstractIdResource;
public class SamplePOJO extends AbstractIdResource {
private String handle;
public String getHandle() {
return handle;
}
public void setHandle(String handle) {
this.handle = handle;
}
}
Resource class is the heart of logics, where all the requests comes in (please see dropwizard documents for more detail)
Shared library has 2 interfaces for convenience, so that developers know the interface methods.
- com.topcoder.core.api.v3.resource.GetResource
- com.topcoder.core.api.v3.resource.DDLResource
com.topcoder.core.sample.resource.SampleResource class holds the methods. Few parameters worth noting here:
- @Auth AuthUser
* The method handles JWT authentication. Refer dropwizard authentication docs for the details. - @APIFieldParam(repClass = Sample.class) FieldSelector
* FieldSelector holds parameters passed from request for single resource retrieval (fields parameter in V3 API). * repClass is the POJO representation class. Request injection class will parse parameter according to the specified representation class. - @APIQueryParam(repClass = Sample.class) QueryParameter
* QueryParameter holds parameters passed from request for multiple resource retrieval (@see V3 API: GET Reserved Parameters)
* repClass is the POJO representation class. Request injection class will parse parameter according to the specified representation class. - @Valid PostPutRequest
* PostPutRequest holds post and put representation class as specified in V3 API doc * Provide POJO class in generics
All output should be wrapped to follow V3 API spec.
- For normal response, use ApiResponseFactory.createFieldSelectorResponse() as shown in the sample. This will wrap the representation POJO to V3 spec.
- For exceptions (errors), create Exception extending APIRuntimeException with appropriate status code, and throw that from application. Jersey's exception handler will catch the exception and parse to respond back with correct exception to the client.
The shared library is assumed to run from main() method of com.topcoder.core.api.v3.dropwizard.APIApplication.
The class will register and initiate libraries to follow V3 protocol. Also purses the class hierarchy to register Resource class that has Jersey's @Path annotation specified.
Application has the flexibility to extend this class to provide its own initializing methods, in case the advice is always call super() for initialize() and run() so that default libraries for API is registered correctly.
| Version | Changes |
|---|---|
| API-3.0.0.9-SNAPSHOT |
Supporting Validation on POST/OUT/PATCH request payload.
PR#177(https://github.com/topcoder-tech/tc1-api-core/pull/177) |
| API-3.0.0.8-SNAPSHOT |
AuthUser contains roles which are extracted from JWT token.
Related stories: |
| API-3.0.0.7-SNAPSHOT | |
| API-3.0.0.6-SNAPSHOT | Additional user's attribute "handle" and "email" are added in JWT payload. 403 Forbidden is returned for logging-in attempt by non-active users. Related stories: |
| API-3.0.0.5-SNAPSHOT | Supports for the authorization. |
| API-3.0.0.4-SNAPSHOT | The request JSON supports "option" parameter. Example: POST /v3/users
{
"param": {
"handle": "jdoe",
....
},
"options" : {
"afterActivationURL": "https://example.topcoder.com/url/redirected/after/activation"
}
}
Related stories: |
| API-3.0.0.3-SNAPSHOT | JWT payload contains the "iss" (issuer) claim which tells a domain where it's issued. (i.e. https://api.topcoder-dev.com) In the authentication process, this is checked whther JWT token is created in the same domain. This version does not have compatibility with the earlier versions. |
| API-3.0.0.2-SNAPSHOT, API-3.0.0.1-SNAPSHOT | Versions in the earliest stage. (Don't use them) |