skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
prowler-cloud/prowler126 installs

jsonapi

Strict JSON:API v1.1 specification compliance. Trigger: When creating or modifying API endpoints, reviewing API responses, or validating JSON:API compliance.

How do I install this agent skill?

npx skills add https://github.com/prowler-cloud/prowler --skill jsonapi
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides guidelines for JSON:API v1.1 compliance and Prowler-specific implementation details. No security risks were detected.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

  • Runlayerwarn

    1/1 file flagged

What does this agent skill do?

Use With django-drf

This skill focuses on spec compliance. For implementation patterns (ViewSets, Serializers, Filters), use django-drf skill together with this one.

SkillFocus
jsonapiWhat the spec requires (MUST/MUST NOT rules)
django-drfHow to implement it in DRF (code patterns)

When creating/modifying endpoints, invoke BOTH skills.


Before Implementing/Reviewing

When a rule is unclear, check the official spec (https://jsonapi.org/format/) for the specific topic before deciding.


Critical Rules (NEVER Break)

Document Structure

  • NEVER include both data and errors in the same response
  • ALWAYS include at least one of: data, errors, meta
  • ALWAYS use type and id (string) in resource objects
  • NEVER include id when creating resources (server generates it)

Content-Type

  • ALWAYS use Content-Type: application/vnd.api+json
  • ALWAYS use Accept: application/vnd.api+json
  • NEVER add parameters to media type without ext/profile

Resource Objects

  • ALWAYS use string for id (even if UUID)
  • ALWAYS use lowercase kebab-case for type
  • NEVER put id or type inside attributes
  • NEVER include foreign keys in attributes - use relationships

Relationships

  • ALWAYS include at least one of: links, data, or meta
  • ALWAYS use resource linkage format: {"type": "...", "id": "..."}
  • NEVER use raw IDs in relationships - always use linkage objects

Error Objects

  • ALWAYS return errors as array: {"errors": [...]}
  • ALWAYS include status as string (e.g., "400", not 400)
  • ALWAYS include source.pointer for field-specific errors

HTTP Status Codes (Mandatory)

OperationSuccessAsyncConflictNot FoundForbiddenBad Request
GET200--404403400
POST201202409404403400
PATCH200202409404403400
DELETE200/204202-404403-

When to Use Each

CodeUse When
200 OKSuccessful GET, PATCH with response body, DELETE with response
201 CreatedPOST created resource (MUST include Location header)
202 AcceptedAsync operation started (return task reference)
204 No ContentSuccessful DELETE, PATCH with no response body
400 Bad RequestInvalid query params, malformed request, unknown fields
403 ForbiddenAuthentication ok but no permission, client-generated ID rejected
404 Not FoundResource doesn't exist OR RLS hides it (never reveal which)
409 ConflictDuplicate ID, type mismatch, relationship conflict
415 UnsupportedWrong Content-Type header

Document Structure

Success Response (Single)

{
  "data": {
    "type": "providers",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "alias": "Production",
      "connected": true
    },
    "relationships": {
      "tenant": {
        "data": {"type": "tenants", "id": "..."}
      }
    },
    "links": {
      "self": "/api/v1/providers/550e8400-..."
    }
  },
  "links": {
    "self": "/api/v1/providers/550e8400-..."
  }
}

Success Response (List)

{
  "data": [
    {"type": "providers", "id": "...", "attributes": {...}},
    {"type": "providers", "id": "...", "attributes": {...}}
  ],
  "links": {
    "self": "/api/v1/providers?page[number]=1",
    "first": "/api/v1/providers?page[number]=1",
    "last": "/api/v1/providers?page[number]=5",
    "prev": null,
    "next": "/api/v1/providers?page[number]=2"
  },
  "meta": {
    "pagination": {"page": 1, "pages": 5, "count": 100},
    "version": "v1"
  }
}

Error Response

{
  "errors": [
    {
      "status": "400",
      "code": "invalid",
      "title": "Invalid attribute",
      "detail": "UID must be 12 digits for AWS accounts",
      "source": {"pointer": "/data/attributes/uid"}
    }
  ]
}

Query Parameters

FamilyFormatExample
pagepage[number], page[size]?page[number]=2&page[size]=25
filterfilter[field], filter[field__op]?filter[status]=FAIL
sortComma-separated, - for desc?sort=-inserted_at,name
fieldsfields[type]?fields[providers]=id,alias
includeComma-separated paths?include=provider,scan.task

Rules

  • MUST return 400 for unsupported query parameters
  • MUST return 400 for unsupported include paths
  • MUST return 400 for unsupported sort fields
  • MUST NOT include extra fields when fields[type] is specified

Common Violations (AVOID)

ViolationWrongCorrect
ID as integer"id": 123"id": "123"
Type as camelCase"type": "providerGroup""type": "provider-groups"
FK in attributes"tenant_id": "...""relationships": {"tenant": {...}}
Errors not array{"error": "..."}{"errors": [{"detail": "..."}]}
Status as number"status": 400"status": "400"
Data + errors{"data": ..., "errors": ...}Only one or the other
Missing pointer{"detail": "Invalid"}{"detail": "...", "source": {"pointer": "..."}}

Relationship Updates

To-One Relationship

PATCH /api/v1/providers/123/relationships/tenant
Content-Type: application/vnd.api+json

{"data": {"type": "tenants", "id": "456"}}

To clear: {"data": null}

To-Many Relationship

OperationMethodBody
Replace allPATCH{"data": [{...}, {...}]}
Add membersPOST{"data": [{...}]}
Remove membersDELETE{"data": [{...}]}

Compound Documents (include)

When using ?include=provider:

{
  "data": {
    "type": "scans",
    "id": "...",
    "relationships": {
      "provider": {
        "data": {"type": "providers", "id": "prov-123"}
      }
    }
  },
  "included": [
    {
      "type": "providers",
      "id": "prov-123",
      "attributes": {"alias": "Production"}
    }
  ]
}

Rules

  • Every included resource MUST be reachable via relationship chain from primary data
  • MUST NOT include orphan resources
  • MUST NOT duplicate resources (same type+id)

Prowler Implementation Notes

Verified in api/src/backend/:

ConcernHow Prowler does it
Librarydjangorestframework-jsonapi 7.x (rest_framework_json_api parsers, filters, renderer base)
Root metaEvery v1 serializer adds {"version": "v1"} (BaseModelSerializerV1.get_root_meta)
Paginationpage[number] / page[size]; meta.pagination has page, pages, count
Searchfilter[search] (SEARCH_PARAM in config/django/base.py)
Async ops202 + task resource body + Content-Location: /api/v1/tasks/{id} header
Validation errorsRaise ModelValidationError(detail=..., code=..., pointer="/data/attributes/<field>") from api/exceptions.py (status serialized as string)
ConflictsConflictException(detail=..., pointer=...) returns 409
Unknown attributesBaseWriteSerializer.validate() rejects them with 400
Auth errorscustom_exception_handler forces 401 for auth/token failures
RLS-hidden objects404, never 403

Spec Reference

  • Implementation: Use django-drf skill for DRF-specific patterns
  • Testing: Use prowler-test-api skill for test patterns

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/prowler-cloud/prowler/jsonapi">View jsonapi on skillZs</a>