API Documentation

Design Choices

File(s)	Comments
config/routes.rb	POST "create" for the path api/v1/admin/assignments/offers intentional. Since the API deviates from the conventional Rails CRUD verbs, we need to explicitly define that we want a create route. This is accomplished using a string rather than a symbol. Routes are prefixed by the role a user has within TAPP
app/controllers/	Some controllers have a before_action filter that runs the corresponding method before the controller action. More information about filters. Some controllers utilize start_transaction_and_rollback_on_exception. The purpose of this function is to perform the designated tasks inside the associated block (e.g. start_transaction_and_rollback_on_exception do ... end). If an error happens inside the block, all of the changes are rolled back which preserves the state of the database.
app/models/	Some models utilize scopes (e.g. scope :method, -> { ... }). Essentially they are syntactic sugar for writing a class method. More info on scopes.
spec/	shoulda_matchers are sprinkled throughout each spec. They provide great test coverage without writing too much boilerplate. Useful for checking validations and associations.
app/serializers/	Most models have an associated serializer which scopes what attributes are rendered in a response. ActiveModelSerializers is the gem used here. app/controllers/concerns/response.rb contains the method render_success which finds the associated serializer to use for a given model. This method and the associated serializer will have to be refactored in the future if certain attributes need to be displayed for a given role.
app/services/	Services are used to breakup large components of a controller to make it appear more readable. AssignmentWageChunkCreateService is an example of this. Use plain Ruby objects to perform controller specific tasks.