# Add Remote Endpoint

> Use when adding a new remote/network endpoint (a RemoteOperation / OCSRemoteOperation) to this Nextcloud Android library, or when the user says "add an endpoint", "new remote operation", "implement this API call", or "wire up <OCS/ocs> API". Scaffolds the models, constants, operation, and tests following the governance package conventions and the standards in AGENTS.md.

- Skill: `nextcloud/add-remote-endpoint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nextcloud/add-remote-endpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nextcloud/add-remote-endpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: nextcloud (https://skillmd.com/u/nextcloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nextcloud/add-remote-endpoint

---


<!--
 ~ SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
 ~ SPDX-License-Identifier: MIT
-->

# Add a remote endpoint

Implement a new `RemoteOperation` for this library the way the existing ones are written. The full,
authoritative standards live in **[AGENTS.md](../../../AGENTS.md)** — this skill is the step-by-step
procedure. When they disagree, AGENTS.md wins.

## 0. Ground yourself in the reference

Read the canonical package before writing anything:

- `library/src/main/java/com/nextcloud/android/lib/resources/governance/` — operations (GET/POST/DELETE)
- `library/src/main/java/com/nextcloud/android/lib/resources/governance/model/` — `@Serializable` models + enums
- `library/src/main/java/com/owncloud/android/lib/ocs/OcsResponse.kt` — shared `OcsResponse<T>`, `ocsJson`, `SEPARATOR`

Pick the existing operation closest to the one you're adding (list-returning GET, single-object GET,
POST with body, DELETE) and mirror its structure.

## 1. Confirm the contract

Establish, from the user or the API: HTTP method, path (base + segments), path/query params, request
body shape (if any), and the JSON response shape. If any of these is unclear, ask before coding.

## 2. Models — under `<feature>.model`

For each new wire type create a Kotlin `@Serializable data class` (or `enum` with `@SerialName`) in
`com.nextcloud.android.lib.resources.<feature>.model`. Never put models beside the operation or in an
unrelated package. Reuse the shared `OcsResponse<T>` envelope — do not model the `ocs`/`data`/`meta`
wrapper yourself.

## 3. Constants

- Reuse `com.owncloud.android.lib.ocs.SEPARATOR` for `"/"` — never inline it.
- Put the base path and each path segment in the operation's `companion object` as `private const val`
  (`ENDPOINT`, `AVAILABLE`, …). No hardcoded endpoint strings, param keys, or headers.

## 4. Operation

Extend `OCSRemoteOperation<T>` and follow the template in AGENTS.md exactly:

- `@Suppress("TooGenericExceptionCaught")` on `run()`.
- Build the method (`GetMethod`/`PostMethod`/`DeleteMethod`), then `return try { … } catch (e: Exception) { failure(e) } finally { method.releaseConnection() }`.
- Guard clause first: `if (status != HttpStatus.SC_OK) return RemoteOperationResult(false, method)`.
  No nested if/else; keep the body linear.
- Decode with `ocsJson.decodeFromString<OcsResponse<T>>(method.getResponseBodyAsString()).ocs.data`.
- Success: `RemoteOperationResult<T>(true, method).apply { resultData = data }` (property, not a setter).
- Keep **≤ 2 `return` keywords** total (guard + `return try`). The success and `failure` values are
  expressions, not returns.
- Add the `private fun failure(e: Exception)` helper with `@Suppress("DEPRECATION")` (for `logMessage`)
  that logs via `Log_OC.e` and returns `RemoteOperationResult(e)`.
- No class-level KDoc that just restates the class name.

## 5. Tests

Add unit tests beside the existing ones in
`library/src/test/java/com/nextcloud/android/lib/resources/<feature>/`, mirroring the governance
parsing tests — feed a sample OCS JSON string through `ocsJson.decodeFromString<OcsResponse<…>>(json)`
and assert the decoded fields.

Add integration test that makes the actual API call and add an instrumented test under
`library/src/androidTest/java/com/nextcloud/android/lib/resources/<feature>/` that runs the operation
against a live server and asserts the `RemoteOperationResult` (mirror the existing `*IT` tests).

## 6. Verify

Verify — `detekt`, `spotlessKotlinCheck`, and `lint` (see `.github/workflows/check.yml`):

```bash
./gradlew :library:compileDebugKotlin
./gradlew :library:testDebugUnitTest --tests "com.nextcloud.android.lib.resources.<feature>.*"
./gradlew :library:detekt
./gradlew :library:spotlessKotlinCheck
./gradlew :library:lint
```

All must pass. Check lines are ≤ 120 (spotless check can't always be relied on locally — see
AGENTS.md). Then review the diff against the "Definition of done" checklist in AGENTS.md and remove
anything unrelated.