OpenAPI SDK readiness

Asana OpenAPI spec score

Octri scored the public spec at https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml for what a code generator can do with it. This is a reading of the document, not a grade of the API.

8.2/ 10
Strong

249 operations · 280 models · 49 tags · OpenAPI 3.0.0

Scored 14 September 2026 · fingerprint 9f791d7d6d55… · spec version 1.0 · server app.asana.com

Document last changed 14 September 2026.

Generate a TypeScript SDK from a spec like thisSee the fourteen rulesScore your own spec

Where the points went

Every rule, heaviest first, with what it cost this document and how much of the surface it touched. Open a row for the locations.

  1. Successful responses declare a schema2.0Clean249 operations clean

    Without a response schema every method returns `unknown`/`any`, so callers get no types and no autocompletion.

    What this rule checks

  2. Shared models live in components and are $ref'd2.00.4 lost1 of 249 operations

    Inline object schemas become anonymous per-operation types. The same model inlined in 20 operations generates 20 near-identical types instead of one.

    • data, has_more, sync An identical inline object (3 fields) appears in 2 operations. Move it to `components.schemas` and $ref it, or the SDK generates 2 separate types.

    What this rule checks

  3. Generated public names do not collide2.00.6 lost24 of 249 operations

    When authored identifiers collapse to the same shared public name, the generator must silently rename one method; callers otherwise cannot predict the SDK surface from the spec.

    • GET /allocations Public method `get` collides with `getAllocation` in namespace `allocations`; the generator emits `getAllocations` instead. Rename the authored operationId from `getAllocations` to `getAllocations_2`; the wire operation remains GET /allocations.
    • GET /budgets/{budget_gid} Public method `get` collides with `getBudgets` in namespace `budgets`; the generator emits `getBudget` instead. Rename the authored operationId from `getBudget` to `getBudget_3`; the wire operation remains GET /budgets/{budget_gid}.
    • GET /custom_types/{custom_type_gid} Public method `get` collides with `getCustomTypes` in namespace `customTypes`; the generator emits `getCustomType` instead. Rename the authored operationId from `getCustomType` to `getCustomType_4`; the wire operation remains GET /custom_types/{custom_type_gid}.
    • GET /goal_relationships Public method `get` collides with `getGoalRelationship` in namespace `goalRelationships`; the generator emits `getGoalRelationships` instead. Rename the authored operationId from `getGoalRelationships` to `getGoalRelationships_5`; the wire operation remains GET /goal_relationships.
    • GET /goals Public method `get` collides with `getGoal` in namespace `goals`; the generator emits `getGoals` instead. Rename the authored operationId from `getGoals` to `getGoals_6`; the wire operation remains GET /goals.
    • 19 more, not listed here.

    What this rule checks

  4. Every path placeholder has a parameter1.5Clean249 operations clean

    An undeclared `{id}` placeholder cannot become a typed method argument, so the generated request path is incomplete or uncompilable.

    What this rule checks

  5. Every operation declares an operationId1.0Clean249 operations clean

    Without one the generator synthesizes a name from the path, which changes whenever the path does. That is a silent breaking change for callers.

    What this rule checks

  6. operationIds read as method names1.00.2 lost13 of 249 operations

    The id becomes the method name. `ActionsActionsGet` generates `client.actions.actionsActionsGet()`; `getActions` generates `client.actions.get()`.

    • POST /access_requests/{access_request_gid}/approve `approveAccessRequest` reads better as `createApproveAccessRequest` at the call site.
    • POST /access_requests/{access_request_gid}/reject `rejectAccessRequest` reads better as `createRejectAccessRequest` at the call site.
    • POST /custom_fields/{custom_field_gid}/enum_options/insert `insertEnumOptionForCustomField` reads better as `createInsertEnumOptionForCustomField` at the call site.
    • POST /portfolios/{portfolio_gid}/duplicate `duplicatePortfolio` reads better as `createDuplicatePortfolio` at the call site.
    • POST /project_templates/{project_template_gid}/instantiateProject `instantiateProject` reads better as `createInstantiateProject` at the call site.
    • 8 more, not listed here.

    What this rule checks

  7. Operations carry a summary or description1.0Clean249 operations clean

    Operation prose becomes the method's doc comment, the text an IDE shows on hover.

    What this rule checks

  8. Request bodies are documented1.00.2 lost1 of 249 operations

    Body field descriptions become the doc comments on generated parameters; without them the SDK ships undocumented arguments.

    • POST /access_requests `createAccessRequest` has an undocumented request body, so every generated parameter for it will be comment-free.

    What this rule checks

  9. Failure responses are declared1.00.2 lost1 of 249 operations

    Declared error schemas become typed errors. Without them every failure surfaces as an untyped generic error.

    • GET /workspaces/{workspace_gid}/workspace_memberships `getWorkspaceMembershipsForWorkspace` declares no 4xx/5xx or default response, so SDK users get no typed error for it.

    What this rule checks

  10. Operations are tagged1.0Clean249 operations clean

    Tags drive namespacing. Untagged operations fall back to a path segment, producing lopsided or `misc` namespaces.

    What this rule checks

  11. No duplicate or equivalent paths1.0Clean175 paths clean

    Paths differing only in parameter NAME are the same route to a server; the generated SDK ends up with two methods that call the same endpoint.

    What this rule checks

  12. Authentication is described1.0CleanDeclared

    Security schemes generate the SDK's auth configuration. A spec without them produces a client with no way to authenticate.

    What this rule checks

  13. Parameters explain their purpose0.750.16 lost4 of 249 operations

    Parameter descriptions become IDE hints on generated method arguments; bare names force SDK users back to the API reference.

    • GET /portfolio_memberships/{portfolio_membership_gid}#path:portfolio_membership_gid `portfolio_membership_gid` has no description, so the generated argument has no IDE guidance.
    • GET /project_memberships/{project_membership_gid}#path:project_membership_gid `project_membership_gid` has no description, so the generated argument has no IDE guidance.
    • GET /team_memberships/{team_membership_gid}#path:team_membership_gid `team_membership_gid` has no description, so the generated argument has no IDE guidance.
    • GET /workspace_memberships/{workspace_membership_gid}#path:workspace_membership_gid `workspace_membership_gid` has no description, so the generated argument has no IDE guidance.

    What this rule checks

  14. A server URL is declared0.5CleanDeclared

    Without a server URL the generated client must ship with an empty or placeholder base URL, adding setup work and easy production misconfiguration.

    What this rule checks

What 8.2 means for an SDK

A strong reading, and the three rules that decide most of it.

A generator has what it needs here: typed methods, named models and doc comments that say something. What is left is polish, and it can wait until after the first release.

Three rules carry six of the 10 points between them. On this document they took 0.96.

Clean

Successful responses declare a schema

249 operations clean

−0.4

Shared models live in components and are $ref'd

1 of 249 operations

−0.6

Generated public names do not collide

24 of 249 operations

What to change first

Every rule that deducted, in the order they cost.

  1. Shared models live in components and are $ref'd

    Move the shape into components.schemas once and $ref it from each operation that returns or accepts it.

  2. Generated public names do not collide

    Rename the authored operationId, or set that operation's SDK namespace. The audit proposes one and can apply it; your tags and the wire operation are left alone. Inside Octri this one has a one-click fix.

  3. operationIds read as method names

    Name the id for the action, not the route. The audit suggests one per operation and can apply it. Inside Octri this one has a one-click fix.

  4. Request bodies are documented

    Describe the body, or the fields inside it. Field-level prose is the one that reaches the SDK's arguments. Inside Octri this one has a one-click fix.

  5. Failure responses are declared

    Declare the failures you actually return, or one `default` response carrying your error shape.

  6. Parameters explain their purpose

    Describe what the parameter does and what a valid value looks like. One line each. Inside Octri this one has a one-click fix.

Score your own spec in OctriRun the free audit

Where to go next

The spec at raw.githubusercontent.comis public. Octri keeps the `info` block, the score, and up to five sample finding locations per rule. The document itself is not stored and is not served from here. The audit predicts what an SDK generator can do with the description; it is not a security review, an uptime measurement or a critique of the API’s design. This page is not affiliated with Asana or Asana Support.