### API Naming Convention

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Suggests using more familiar terms for API elements compared to the TeamCity REST API. For example, 'buildTypes' in the REST API should be 'BuildConfiguration' in the library.

```APIDOC
REST API: buildTypes -> Library API: BuildConfiguration
REST API: source-buildType -> Library API: dependsOnBuildConfiguration
```

--------------------------------

### Cached Build State (Coroutines)

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/README.md

Demonstrates the caching mechanism for build states when using the coroutines non-blocking API. Repeated calls to get the state return cached values, ensuring fast retrieval even if the actual state changes.

```kotlin
val tc = TeamCityInstanceBuilder("https://myserver.local").withGuestAuth().build()
val build = tc.builds().latest()!!

val first = build.getState()  // suspending call
delay(1000000L)
val second = build.getState() // fast call; won't suspend, returns cached value 
assert(first == second)       // the check will always pass, even if the build state has changed
```

--------------------------------

### Publishing Process

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Outlines the steps for publishing a new version, which involves ensuring the 'Build on internal JetBrains' TeamCity instance' build succeeds and then promoting it to the 'Publish' build configuration.

```APIDOC
1. Ensure 'TeamCity Rest Client > Build on internal JetBrains' TeamCity instance' build succeeds.
2. Promote the build to the 'Publish' build configuration.
```

--------------------------------

### Versioning Strategy (Semantic Versioning)

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Explains the library's adherence to semantic versioning (`<major>.<minor>.<patch>`). Details how to increment each component based on the type of changes made.

```APIDOC
Versioning format: `<major>.<minor>.<patch>`
- Patch: Increment for bug fixes (automated via TeamCity build).
- Minor: Increment for new API additions (update `gradle.properties`).
- Major: Increment for removing deprecated API or adding significant new APIs (update `gradle.properties`).
```

--------------------------------

### Download Artifacts (Blocking API)

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/README.md

Downloads *.zip artifacts from the latest successful build with a specific tag for a given build configuration using the blocking API. This method will halt execution until the download is complete.

```kotlin
val docs = BuildConfigurationId("Kotlin_StandardLibraryDocumentation")
val build = TeamCityInstanceBuilder("https://teamcity.jetbrains.com")
    .withGuestAuth()
    .buildBlockingInstance() 
    .builds()
    .fromConfiguration(docs)
    .withTag("publish")
    .latest() // will block execution until response received

// will block execution until response received
build!!.downloadArtifacts("*.zip", File("out"))
```

--------------------------------

### Download Artifacts (Coroutines)

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/README.md

Downloads *.zip artifacts from the latest successful build with a specific tag for a given build configuration. It uses the coroutines non-blocking API and saves the artifacts to a specified directory.

```kotlin
val docs = BuildConfigurationId("Kotlin_StandardLibraryDocumentation")
val build = TeamCityInstanceBuilder("https://teamcity.jetbrains.com").withGuestAuth().build()
    .builds()
    .fromConfiguration(docs)
    .withTag("publish")
    .latest() // suspending call

// suspending call
build!!.downloadArtifacts("*.zip", File("out"))
```

--------------------------------

### Changelog Management

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Instructs contributors to document changes in the `CHANGELOG.md` file under the `[Unreleased]` section. The header should be updated to the actual version before publishing.

```APIDOC
Describe changes in `CHANGELOG.md` under the `[Unreleased]` section.
Update the section header to the actual version before publishing a new release.
```

--------------------------------

### Backward Compatibility Policy

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Stresses the importance of maintaining binary and source backward compatibility. New functions can be added, but existing ones should be deprecated rather than removed or have their signatures changed.

```APIDOC
Add new functions to interfaces.
Do not remove functions or change signatures; use `@Deprecated` annotation instead.
Deprecated elements may be removed in a future major version.
```

--------------------------------

### Run Build with Parameters (Coroutines)

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/README.md

Triggers a build on a TeamCity server with specified parameters using the coroutines non-blocking API. It requires authentication details and the build configuration ID.

```kotlin
val tc = TeamCityInstanceBuilder("https://myserver.local")
    .withHttpAuth("login", "password")
    .build()

// suspending call
val buildConfiguration = tc.buildConfiguration(BuildConfigurationId("BuildConfId"))
// suspending call
val build = buildConfiguration.runBuild( 
    parameters = mapOf("myparameter1" to "value", "myparameter2" to "value")
)
```

--------------------------------

### Gradle Dependency

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/README.md

Specifies how to add the teamcity-rest-client as a dependency in a Gradle project. It includes the necessary repository and dependency declarations for Maven Central.

```gradle
repositories {
    maven {
        url "https://packages.jetbrains.team/maven/p/teamcity-rest-client/teamcity-rest-client"
    }
}

dependencies {
    compile "org.jetbrains.teamcity:teamcity-rest-client:PACKAGE_VERSION"
}
```

--------------------------------

### Typed Interfaces for Properties

Source: https://github.com/jetbrains/teamcity-rest-client/blob/master/CONTRIBUTING.md

Recommends using typed interfaces instead of generic maps like `Map<String, String>` for standard API object properties to improve usability and reduce the need for users to consult REST API documentation.

```APIDOC
Use typed interfaces (e.g., `BuildConfiguration`) instead of `Map<String, String>` for standard properties.
`Map<String, String>` is acceptable for user-defined or custom non-standard properties.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.