Topcoder preferences api - swagger specification and implementation

Challenge Objectives

• To set up Swagger specification for 3 api endpoints to manage a user’s newsletter preferences

• To implement the 3 api endpoints in Nodejs

 

Project Background

• Topcoder has been upgrading its backend services

• One of the services is the newsletter preferences api

• We are upgrading it to version 5

 

Technology Stack

• Swagger (version 2)

• Nodejs (version 10)

• Mailchimp (API version 3)

• Dynamodb

 

Code access

You are writing the app from scratch and thus no existing code base will be shared in the contest forum

 

Individual requirements

Create Swagger Specification (Major Requirement)

• We need you to define three api endpoints.

  • HEAD /v5/users/:userId/preferences

  • GET /v5/users/:userId/preferences (referred to as get preferences in further discussion)

  • PUT /v5/users/:userId/preferences (referred to as update preferences in further discussion)

• Head request will only deal with response status and headers

• Get preferences API will read the preferences from Mailchimp

• Update preferences API will update the preferences in Mailchimp as well as in Dynamodb

• The schema will be shared in the contest forum.

 

Implement the endpoints (Major Requirement)

• After you have defined the endpoints in swagger, proceed to implement them in Nodejs version 10.

• Kindly use Topcoder’s middleware for checking authentication (both user token and m2m token). Reference

• Kindly provide POSTMAN collection to verify the endpoints.

• Get preferences will read the preferences of the requested user, identified through userId path parameter. It will read the preferences in MailChimp - where we will be using “Tags” feature to store the preferences. We will support three tags for now

  • Data Science Newsletter

  • Design Newsletter

  • Dev Newsletter

• Update preferences will update the preferences in both MailChimp and Dynamodb.

 

Deployment guide and validation document

Provide a deployment guide to deploy the nodejs app locally. No verification document is expected - the POSTMAN collection that you need to provide itself is the verification step here.

You are not expected to provide steps to set up MailChimp accounts or Dynamodb tables. However, outline the environment variables that are needed for the app in your deployment guide.

 

Important Notes

• The endpoints will need authentication through jwt tokens.

• We will share a document with you, outlining the v5 standards that we you will be following.

• No pagination is expected for any of the endpoints

• Each endpoint is expected to return the correct http status code, based on the request status.

• For reference, kindly check out the swagger specification for the submission api. Reference. You can use this as reference if you have any doubts when writing the specification for the preferences resource.

• The authorization will be using the Authorization header, with the Bearer <token> as the value. <token> in this case will be the jwt token.

• You are also expected to follow the conventions used in the submission api code base when writing your Nodejs app. Reference.

• IMPORTANT: Mailchimp expects the member, whose preferences are being fetched or updated to already exist in their system. Thus, when making the request(s) to MailChimp, if it responds indicating that the user was not found, you need to create the user in MailChimp. In case of updating the preferences, you will create the user in MailChimp and then set the preferences. In case of getting preferences, you will create the user in MailChimp and responding with an empty array, indicating no tag is active.

• You can assume that “Data Science Newsletter”, “Dev Newsletters” and “Design Newsletter” tags are already created in MailChimp. You need not provide instructions on how to create them, or write code to create them.

• You need to make the List, under which the members will exist, configurable.

• We will share details of the API that you need to call, to convert the userId to email address, which is then used when making the request to MailChimp.

Final Submission Guidelines

Zip your code base along with the deployment guide, swagger specification and POSTMAN collection and upload it to Topcoder.