courses.raml

#%RAML 1.0
title: Course Reserves API
version: v1
protocols: [ HTTP, HTTPS ]
baseUri: http://github.com/org/folio/mod-courses

documentation:
    - title: Course Reserves API
      content: API calls to perform CRUD on item reservations for courses
    - title: Overview
      content: !include overview.md

types:
    course: !include course.json
    courses: !include courses.json
    courseListing: !include courselisting.json
    courseListings: !include courselistings.json
    instructor: !include instructor.json
    instructors: !include instructors.json
    reserve: !include reserve.json
    reserves: !include reserves.json
    role: !include role.json
    roles: !include roles.json
    term: !include term.json
    terms: !include terms.json
    courseType: !include coursetype.json
    courseTypes: !include coursetypes.json
    department: !include department.json
    departments: !include departments.json
    processingStatus: !include processingstatus.json
    processingStatuses: !include processingstatuses.json
    copyrightStatus: !include copyrightstatus.json
    copyrightStatuses: !include copyrightstatuses.json
    errors: !include raml-util/schemas/errors.schema

traits:
    pageable: !include raml-util/traits/pageable.raml
    searchable: !include raml-util/traits/searchable.raml
    language: !include raml-util/traits/language.raml
    validate: !include raml-util/traits/validation.raml

resourceTypes:
    collection: !include raml-util/rtypes/collection.raml
    collection-item: !include raml-util/rtypes/item-collection.raml
    get-delete-only: !include raml-util/rtypes/get-delete.raml

/coursereserves:
    /courselistings:
        description: "Handle listings for a course"
        type:
            collection:
                exampleCollection: !include examples/courselistings.json
                exampleItem: !include examples/courselisting.json
                schemaCollection: courseListings
                schemaItem: courseListing
        get:
            description: "Return a list of listings"
            is: [
                searchable: {description: "with valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new listing"
            is: [ validate ]
        delete:
            description: "Delete all listings"
            is: [ validate ]
            responses:
                204:
                    description: "All listings deleted"
                400:
                    description: "Bad request, e.g. unknown tenant"
                    body:
                      text/plain:
                        example: tenant not found
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{listing_id}:
            description: "With provided listing id"
            type:
                collection-item:
                    exampleItem: !include examples/courselisting.json
                    schema: courseListing
            get:
            put:
                description: "Update a listing by id"
            delete:
            /courses:
                description: "Handle courses for a listing"
                type:
                    collection:
                        exampleCollection: !include examples/courses.json
                        exampleItem: !include examples/course.json
                        schemaCollection: courses
                        schemaItem: course
                get:
                    is: [
                        searchable: {description: "with valid searchable fields", example: "name=aaa"},
                        pageable
                    ]
                    description: "Return a list of courses"
                post:
                    description: "Create a new course"
                    is: [ validate ]
                delete:
                    description: "Delete all courses"
                    is: [ validate ]
                    responses:
                        204:
                            description: "All courses deleted"
                        400:
                            description: "Bad request, e.g. malformed listing_id"
                            body:
                              text/plain:
                                example: listing_id is not a UUID
                        500:
                            description: "Internal server error"
                            body:
                                text/plain:
                                    example: "Internal server error"
                /{course_id}:
                    description: "Provide the course id"
                    type:
                        collection-item:
                            exampleItem: !include examples/course.json
                            schema: course
                    get:
                    put:
                        description: "Update a course by id"
                        is: [ validate ]
                    delete:

            /instructors:
                description: "Handle instructors for a listing"
                type:
                    collection:
                        exampleCollection: !include examples/instructors.json
                        exampleItem: !include examples/instructor.json
                        schemaCollection: instructors
                        schemaItem: instructor
                get:
                    description: "Return a list of instructors"
                    is: [
                        searchable: {description: "with valid searchable fields", example: "name=aaa"},
                        pageable
                    ]
                post:
                    description: "Create a new instructor"
                    is: [ validate ]
                delete:
                    description: "Delete all instructors"
                    is: [ validate ]
                    responses:
                        204:
                            description: "All instructors deleted"
                        400:
                            description: "Bad request, e.g. malformed listing_id"
                            body:
                              text/plain:
                                example: listing_id is not a UUID
                        500:
                            description: "Internal server error"
                            body:
                                text/plain:
                                    example: "Internal server error"
                /{instructor_id}:
                    description: "With provided instructor id"
                    type:
                        collection-item:
                            exampleItem: !include examples/instructor.json
                            schema: instructor
                    get:
                    put:
                        description: "Update an instructor by id"
                    delete:
            /reserves:
                description: "Handle reserves for a listing"
                type:
                    collection:
                        exampleCollection: !include examples/reserves.json
                        exampleItem: !include examples/reserve.json
                        schemaCollection: reserves
                        schemaItem: reserve
                get:
                    description: "Return a list of reserves"
                    queryParameters:
                        expand:
                            description: Whether or not to expand the id fields
                            type: string
                            required: false
                    is: [
                        searchable: {description: "with valid searchable fields", example: "name=aaa"},
                        pageable
                    ]
                post:
                    description: "Create a new reserve"
                    is: [ validate ]
                delete:
                    description: "Delete all reserves"
                    is: [ validate ]
                    responses:
                        204:
                            description: "All reserves deleted"
                        400:
                            description: "Bad request, e.g. malformed listing_id"
                            body:
                              text/plain:
                                example: listing_id is not a UUID
                        500:
                            description: "Internal server error"
                            body:
                                text/plain:
                                    example: "Internal server error"
                /{reserve_id}:
                    description: "With provided reserve id"
                    type:
                        collection-item:
                            exampleItem: !include examples/reserve.json
                            schema: reserve
                    get:
                    put:
                        description: "Update a reserve by id"
                        is: [ validate ]
                    delete:
    /roles:
        description: "Handle roles for course instructors"
        type:
            collection:
                exampleCollection: !include examples/roles.json
                exampleItem: !include examples/role.json
                schemaCollection: roles
                schemaItem: role
        get:
            description: "Return a list of roles"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new role"
            is: [ validate ]
        delete:
            description: "Delete all roles"
            is: [ validate ]
            responses:
                204:
                    description: "All roles deleted"
                400:
                    description: "Bad request, e.g. unknown tenant"
                    body:
                      text/plain:
                        example: "tenant not found"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{role_id}:
            description: "With provided role id"
            type:
                collection-item:
                    exampleItem: !include examples/role.json
                    schema: role
            get:
            put:
                description: "Update a role by id"
                is: [ validate ]
            delete:
    /terms:
        description: "Handle terms for courses"
        type:
            collection:
                exampleCollection: !include examples/terms.json
                exampleItem: !include examples/term.json
                schemaCollection: terms
                schemaItem: term
        get:
            description: "Return a list of terms"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new term"
            is: [ validate ]
        delete:
            description: "Delete all terms"
            is: [ validate ]
            responses:
                204:
                    description: "All terms deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{term_id}:
            description: "With provided term id"
            type:
                collection-item:
                    exampleItem: !include examples/term.json
                    schema: term
            get:
            put:
                description: "Update a term by id"
                is: [ validate ]
            delete:
    /coursetypes:
        description: "Handle types for courses"
        type:
            collection:
                exampleCollection: !include examples/coursetypes.json
                exampleItem: !include examples/coursetype.json
                schemaCollection: courseTypes
                schemaItem: courseType
        get:
            description: "Return a list of course types"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new course type"
            is: [ validate ]
        delete:
            description: "Delete all course types"
            is: [ validate ]
            responses:
                204:
                    description: "All course types deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{type_id}:
            description: "With provided course type id"
            type:
                collection-item:
                    exampleItem: !include examples/coursetype.json
                    schema: courseType
            get:
            put:
                description: "Update a course type by id"
                is: [ validate ]
            delete:
    /departments:
        description: "Handle departments"
        type:
            collection:
                exampleCollection: !include examples/departments.json
                exampleItem: !include examples/department.json
                schemaCollection: departments
                schemaItem: department
        get:
            description: "Return a list of departments"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new department"
            is: [ validate ]
        delete:
            description: "Delete all departments"
            is: [ validate ]
            responses:
                204:
                    description: "All departments deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{department_id}:
            description: "With provided department id"
            type:
                collection-item:
                    exampleItem: !include examples/department.json
                    schema: department
            get:
            put:
                description: "Update a department by id"
                is: [ validate ]
            delete:
    /processingstatuses:
        description: "Handle processing status"
        type:
            collection:
                exampleCollection: !include examples/processingstatuses.json
                exampleItem: !include examples/processingstatus.json
                schemaCollection: processingStatuses
                schemaItem: processingStatus
        get:
            description: "Return a list of statuses"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new status"
            is: [ validate ]
        delete:
            description: "Delete all statuses"
            is: [ validate ]
            responses:
                204:
                    description: "All statuses deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{status_id}:
            description: "With provided status id"
            type:
                collection-item:
                    exampleItem: !include examples/processingstatus.json
                    schema: processingStatus
            get:
            put:
                description: "Update a status by id"
                is: [ validate ]
            delete:
    /copyrightstatuses:
        description: "Handle copyright status"
        type:
            collection:
                exampleCollection: !include examples/copyrightstatuses.json
                exampleItem: !include examples/copyrightstatus.json
                schemaCollection: copyrightStatuses
                schemaItem: copyrightStatus
        get:
            description: "Return a list of copyright statuses"
            is: [
                searchable: { description: "With valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new copyright status"
            is: [ validate ]
        delete:
            description: "Delete all copyright statuses"
            is: [ validate ]
            responses:
                204:
                    description: "All statuses deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{status_id}:
            description: "With provided status id"
            type:
                collection-item:
                    exampleItem: !include examples/copyrightstatus.json
                    schema: copyrightStatus
            get:
            put:
                description: "Update a status by id"
                is: [ validate ]
            delete:
    /courses:
        description: "Handle courses"
        type:
            collection:
                exampleCollection: !include examples/courses.json
                exampleItem: !include examples/course.json
                schemaCollection: courses
                schemaItem: course
        get:
            description: "Return a list of courses"
            is: [
                searchable: {description: "with valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new course"
            is: [ validate ]
        delete:
            description: "Delete ALL courses"
            is: [ validate ]
            responses:
                204:
                    description: "All courses delete"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{course_id}:
            description: "With provided id"
            type:
                collection-item:
                    exampleItem: !include examples/course.json
                    schema: course
            get:
            put:
                description: "Update a course by id"
            delete:
    /reserves:
        description: "Handle reserves"
        type:
            collection:
                exampleCollection: !include examples/reserves.json
                exampleItem: !include examples/reserve.json
                schemaCollection: reserves
                schemaItem: reserve
        get:
            description: "Return a list of reserves"
            queryParameters:
                expand:
                    description: What fields to expand
                    type: string
                    required: false
            is: [
                searchable: {description: "with valid searchable fields", example: "name=aaa"},
                pageable
            ]
        post:
            description: "Create a new reserve"
            is: [ validate ]
        delete:
            description: "Delete ALL reserves"
            is: [ validate ]
            responses:
                204:
                    description: "All reserves deleted"
                500:
                    description: "Internal server error"
                    body:
                        text/plain:
                            example: "Internal server error"
        /{reserve_id}:
            description: "With provided reserve id"
            type:
                collection-item:
                    exampleItem: !include examples/reserve.json
                    schema: reserve
            get:
            put:
                description: "Update a reserve by id"
                is: [ validate ]
            delete: