src.main.kotlin.com.gabrielfeo.develocity.api.ProjectsApi.kt Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of develocity-api-kotlin Show documentation
A library to use the Develocity API in Kotlin
The newest version!
package com.gabrielfeo.develocity.api

import com.gabrielfeo.develocity.api.internal.infrastructure.CollectionFormats.*
import retrofit2.http.*
import retrofit2.Response
import okhttp3.RequestBody
import com.squareup.moshi.Json

import com.gabrielfeo.develocity.api.model.ApiProblem
import com.gabrielfeo.develocity.api.model.PageQuery
import com.gabrielfeo.develocity.api.model.Project
import com.gabrielfeo.develocity.api.model.ProjectGroup
import com.gabrielfeo.develocity.api.model.ProjectGroupsPage
import com.gabrielfeo.develocity.api.model.ProjectsPage

import com.gabrielfeo.develocity.api.model.*

@JvmSuppressWildcards
interface ProjectsApi {
    /**
     * Create or update a project.
     * **<mark>Beta:</mark>** Create a new project in Develocity or update an existing project. When updating, any optional fields that are omitted from the request, but were previously set on the project, will be unset/removed. An existing project's identifier cannot be updated. If the update contains a id that does not match the current id, then the operation will fail with a Bad Request response. 
     * Responses:
     *  - 200: The project was created or it was updated successfully.
     *  - 400: The request body is malformed or contains invalid values for at least one of the properties.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param projectId The ID of the project.
     * @param project 
     * @return [Project]
     */
    @PUT("api/projects/{projectId}")
    suspend fun createOrUpdateProject(@Path("projectId") projectId: kotlin.String, @Body project: Project): Project

    /**
     * Create or update a project group.
     * **<mark>Beta:</mark>** Create a new project group in Develocity or update an existing project group. When updating, any optional fields that are omitted from the request, but were previously set on the project group, will be unset/removed. An existing project group's identifier cannot be updated. If the update contains a id that does not match the current id, then the operation will fail with a Bad Request response. 
     * Responses:
     *  - 200: The project group was created or it was updated successfully.
     *  - 400: The request body is malformed or contains invalid values for at least one of the properties.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param projectGroupId The ID of the project group.
     * @param projectGroup 
     * @return [ProjectGroup]
     */
    @PUT("api/project-groups/{projectGroupId}")
    suspend fun createOrUpdateProjectGroup(@Path("projectGroupId") projectGroupId: kotlin.String, @Body projectGroup: ProjectGroup): ProjectGroup

    /**
     * Delete a project group.
     * **<mark>Beta:</mark>** Delete a project group. 
     * Responses:
     *  - 200: The projectId referenced an existing project group and it was deleted.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param projectGroupId The ID of the project group.
     * @return [Unit]
     */
    @DELETE("api/project-groups/{projectGroupId}")
    suspend fun deleteProjectGroup(@Path("projectGroupId") projectGroupId: kotlin.String): Unit

    /**
     * Get a project.
     * **<mark>Beta:</mark>** Gets a specific project. 
     * Responses:
     *  - 200: The requested project.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param projectId The ID of the project.
     * @return [Project]
     */
    @GET("api/projects/{projectId}")
    suspend fun getProject(@Path("projectId") projectId: kotlin.String): Project

    /**
     * Get a project group
     * **<mark>Beta:</mark>** Gets a specific project group. 
     * Responses:
     *  - 200: The requested project group.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param projectGroupId The ID of the project group.
     * @return [ProjectGroup]
     */
    @GET("api/project-groups/{projectGroupId}")
    suspend fun getProjectGroup(@Path("projectGroupId") projectGroupId: kotlin.String): ProjectGroup

    /**
     * Lists project groups.
     * **<mark>Beta:</mark>** Returns a list of all project groups. If there are a lot of project groups, then all pages will need to be retrieved in order to retrieve the full list of project groups. The default number of project groups per page is 100. 
     * Responses:
     *  - 200: A list of project groups.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param pageNumber The index of the page to retrieve. The first page's index is zero.  (optional, default to 0)
     * @param pageSize The maximum number of elements to include in the fetched page. (optional)
     * @return [ProjectGroupsPage]
     */
    @GET("api/project-groups")
    suspend fun listProjectGroups(@Query("pageNumber") pageNumber: kotlin.Int? = 0, @Query("pageSize") pageSize: kotlin.Int? = null): ProjectGroupsPage

    /**
     * Lists Projects.
     * **<mark>Beta:</mark>** Returns a paged list of all projects. If there are a lot of projects, then all pages will need to be retrieved in order to retrieve the full list of projects. The default number of projects per page is 1,000. 
     * Responses:
     *  - 200: A list of projects known to Develocity.
     *  - 403: The authenticated user has insufficient permissions.
     *  - 404: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
     *
     * @param pageNumber The index of the page to retrieve. The first page's index is zero.  (optional, default to 0)
     * @param pageSize The maximum number of elements to include in the fetched page. (optional)
     * @return [ProjectsPage]
     */
    @GET("api/projects")
    suspend fun listProjects(@Query("pageNumber") pageNumber: kotlin.Int? = 0, @Query("pageSize") pageSize: kotlin.Int? = null): ProjectsPage

}