REST API, Repository Provisioning, Security Automation, Pagination, and Infrastructure-as-Code Patterns: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic sequence: preserve → identify → compare → correct → verify

1. Preserve timestamp, method, redacted URL, status, response body, request-log evidence, and automation version.
2. Confirm Nexus version/edition/runtime and exact base URL.
3. Inspect local Swagger path/schema.
4. Check authentication without printing credentials; then required privileges.
5. GET actual repository/security state and compare owned fields.
6. For content symptoms, inspect repository type/group/routing, authorization, components/assets, proxy/cache/upstream, database/blob/disk, logs/tasks/metrics.
7. Apply the smallest correction and rerun a controlled request.

2. Failure mode: a password or token is hard-coded

Once a real credential is committed or printed into CI logs, removing the line is insufficient. Rotate/revoke according to policy, prevent future logging, inspect where it was used, and review retained artifacts. Demonstrate only with password-FAKE_DO_NOT_USE.

# Broken pattern — intentionally fake.
AUTH = ("svc-learner-api", "password-FAKE_DO_NOT_USE")
# Better: runtime injection; never print the value.
AUTH = (os.environ["NEXUS_USER"], os.environ["NEXUS_PASSWORD"])

3. Failure mode: rerun tries to create the same resource

First run succeeds; second receives conflict/create failure. Root cause: action scripting rather than reconciliation. GET deterministic name, create if absent, normalize/compare if present, PUT only drift, then fresh GET verification. Do not append timestamps to resource names—that converts a bug into sprawl.

4. Failure mode: first-page success hides missing artifacts

HTTP can succeed while the algorithm fails:

# Broken
items = requests.get(url, params={"repository": repo}, auth=auth).json()["items"]
# Correct control condition
while True:
    body = requests.get(url, params=params, auth=auth).json()
    items.extend(body["items"])
    token = body.get("continuationToken")
    if token is None:
        break
    params["continuationToken"] = token

Compare complete results with a known fixture inventory or another trustworthy observation where practical.

5. Failure mode: field or endpoint changed after upgrade

400 validation errors, unknown/missing fields, or 404 require comparison of server version, automation/client version, current Swagger, redacted payload, and release notes. Do not delete fields until the request passes; understand the compatibility change.

6. Failure mode: 400 or 409 is ignored

7. Intentionally broken example: DELETE points at the wrong base URL

from urllib.parse import urlparse
import os
base = os.environ["NEXUS_URL"]
expected = "127.0.0.1"
host = urlparse(base).hostname
if host != expected:
    raise SystemExit(f"REFUSE destructive action: expected {expected}, got {host}")
name = "learner-api-hosted"
if not name.startswith("learner-"):
    raise SystemExit("REFUSE destructive action: unmanaged resource name")
print("preflight passed; destructive call would still require explicit --destroy")

A machine-verifiable allowlist, naming marker, dry-run plan, and separate destruction flag are stronger than a generic “Are you sure?” prompt.

8. Failure mode: automation and humans fight over one field

Stop automatic reconciliation for the disputed field, preserve current state and impact, agree on an owner, update desired state or restore the reviewed configuration once, then resume. This is an ownership failure, not a Nexus defect.

9. Authentication and authorization failures

401 means Nexus did not accept the presented identity; 403 means it accepted the identity but denied the action. Test a harmless endpoint the identity should be allowed to call, then inspect roles/privileges. Do not expose Authorization headers through verbose curl output in shared logs.

10. Network/TLS failure versus API failure

Connection timeout, DNS failure, TLS validation, proxy misconfiguration, or reverse-proxy context-path mismatch can occur before Nexus returns application-level HTTP. Reuse Chapter 17's network model and never globally disable TLS verification to make automation pass.

11. Performance: separate client fan-out from Nexus load

Measure automation request rate/concurrency, Nexus request latency/errors, database latency/pool, blob IO when content is involved, task overlap, retries/backoff, and upstream latency for proxy tests. Pagination is a correctness mechanism, not permission to launch unbounded parallel calls.

12. Evidence packet

• Nexus version/edition/runtime and Swagger checksum.
• Automation version and desired-state checksum.
• Redacted method/path/status/response.
• Resource ownership marker.
• Before/after normalized GET state.
• Complete pagination count and final null token.
• Positive/negative authorization tests.
• Relevant logs with credentials redacted.
• Correction and final verification.

13. Knowledge check

14. Summary and next step

You can diagnose automation at the correct layer: target, schema, identity, privilege, state diff, pagination, repository behavior, database/blob/log evidence, and client function. Lesson 5 integrates these skills into a complete disposable topology.

Official references and version notes

• Sonatype: Automation / REST API — OpenAPI/Swagger location, API integration, and Jetty 12 URL-encoding requirements.
• Sonatype: Nexus Repository API Reference — current endpoint catalog and request/response models.
• Sonatype: Repositories API — generic and format/type-specific repository configuration endpoints.
• Sonatype: Components API — component list/get/upload/delete behavior and continuation tokens.
• Sonatype: Pagination — continuation-token iteration contract.
• Sonatype: Security Management API — users, roles, privileges, content selectors, LDAP/SAML/OIDC boundaries.
• Sonatype: Authentication — local/external authentication and automation identity boundaries.
• Sonatype: User Tokens — current self-hosted Pro entitlement and token behavior.
• Sonatype: System Requirements — Java/database/storage baseline.