Challenge Overview
Challenge Objectives
-
Design API specification (Swagger)
Project Background
-
We’re building an api to manage Taas jobs
-
We’re designing the application backend in this challenge
-
In the follow-up challenges we will develop the backend API and frontend and integrate the two.
Technology Stack
-
Swagger Open API Specification
-
ERD
-
Relational Database - PostgreSQL
Individual requirements
We’re aiming to create two things in this challenge:
-
REST API specification document (swagger)
-
Implementation notes for the api
These are the entities that will be managed by the api:
-
Jobs - definition of a job posting (ex company X is looking for N backend developers for engagement from Oct 1st through December 31st, with skills in Java, Postgres and Docker)
-
JobCandidates - members that applied for a job posting
-
ResourceBookings - actual job engagements that store what job the member was selected for, date range, payments rates
Jobs will have the following attributes:
-
Id - unique identifier, uuid
-
projectId - external id, integer
-
externalId - external id, string
-
Description - text
-
startDate - timestamp
-
endDate - timestamp
-
numPositions (how many positions are open for this job)
-
resourceType - string field
-
rateType - enum string with values hourly, daily, weekly, monthly
-
Skills - list of skills required for the job (ex Java, Postgres, etc). Skills are managed in an external api and we’re only storing skill id, not actual skill names
-
Status - enum string field with allowed values: sourcing, in-review, assigned, closed, cancelled
JobCandidates entity will have the following attributes:
-
Id
-
jobId
-
userId
-
Status - enum string field with values: open, selected, shortlist, rejected
ResourceBookings entity will have the following attributes:
-
Id
-
projectId
-
userId
-
Status - enum string with values: assigned, in-progress, completed
-
startDate - timestamp
-
endDate - timestamp
-
memberRate - float value
-
CustomerRate - float value
-
rateType - enum, same as the one in Jobs entity
Expected workflow for api users is:
-
Customer creates a job posting (create job entity - status=sourcing)
-
Members apply to the job (create jobRequest entity - status=open)
-
Customer reviews member applications and updates job candidates status - shortlist, rejected
-
Customer selects members for the engagement (candidate status=selected)
-
Job posting is closed (status=assigned)
Your task is to design the API specification (swagger) and provide implementation notes for the followup challenge for each of the defined endpoints (no need to go into too much detail, just mention what the endpoint is doing and if there is any custom logic that needs to be implemented)
Note that Bookings api will not manage users (we’re only storing userIds and don’t need to validate them), nor will the api manage job skills (again we’re only storing skill ids) - external apis can provide details for these objects and it’s up to the consumer application to call these apis if needed.
API will need CRUD endpoints for each of the entities. User authentication will be done using standard topcoder JWT tokens (Authorization: Bearer {{token}} in the request headers) - all requests will require an authenticated user.
Not all users will be able to do all the actions, nor will all the users be able to see all the attributes. Assume any user can create a Job and any user can apply to the job. Resource bookings will only be managed (CRUD) by users with ‘bookingManager’ role (roles are available in the JWT token) and assigned user will only be able to fetch the booking, but won’t be able to see the ‘customerRate’ attribute.
All entities should have timestamps (createdAt, updatedAt) and createdBy and updatedBy fields.
General for all requirements
Follow the Topcoder API v5 standards (document posted in the forums)
What To Submit
Submit a Swagger API specification