What We Are Enforcing

The mybank-oauth-check ruleset requires every API to:

• Use an OAuth2 security definition (type must match oauth2)
• Reference the approved myBank provider via x-ibm-oauth-provider
• Declare at least one explicit scope
• Never use the implicit grant
• Never clear security at the operation level with an empty array

Step 1 — Create the Governance Ruleset

In the provider org, open API Governance → Rulesets and create a new ruleset named mybank-oauth-check (version 1.0.0). Paste the rules below, or import the YAML as a ruleset file.

Note: API Connect Governance rulesets are based on the open-source Spectral linter. The given / then / severity shape you write here is the same Spectral rule model — API Connect runs those checks as governance scans and scorecards.

name: mybank-oauth-check
title: myBank-oauth-check
description: ""
ruleset_version: 1.0.0

rules:
  - title: no-implicit-grant-type
    id: 4cf01579-a7f6-4ac2-8bf9-7ab41da14162
    name: no-implicit-grant-type
    version: 1.0.0
    description: Implicit grant is disallowed org-wide.
    given:
      $.securityDefinitions[?(@.type=='oauth2')]
    severity: error
    then:
      - function: schema
        functionOptions:
          schema:
            type: object
            required:
              - flow
            properties:
              flow:
                not:
                  enum:
                    - implicit
                type: string

  - title: no-operation-level-security-bypass
    id: 85d45013-144e-4bbb-915e-b253a505512a
    name: no-operation-level-security-bypass
    version: 1.0.0
    description: No operation may override the API-level requirement with an empty security array.
    given:
      $.paths[*][*].security
    severity: error
    then:
      - function: schema
        functionOptions:
          schema:
            type: array
            minItems: 1

  - title: oauth-provider-registered
    id: 94fcbbe3-eac5-4191-b63d-2778a85b874b
    name: oauth-provider-registered
    version: 1.0.0
    description: Every security definition must reference the approved myBank OAuth2 provider.
    given:
      $.securityDefinitions[*]
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - x-ibm-oauth-provider
          properties:
            x-ibm-oauth-provider:
              type: string
              pattern: ^inEdgeOAuth2Provider-\d+\.\d+\.\d+-[a-f0-9]{4}$

  - title: oauth-required-scopes-defined
    id: 689ad9c9-d3e5-4c23-88d2-346d8d808e03
    name: oauth-required-scopes-defined
    version: 1.0.0
    description: Every OAuth2 security definition must declare at least one explicit scope.
    given:
      $.securityDefinitions[*]
    severity: error
    then:
      field: scopes
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  - title: oauth-security-definition
    id: 84743e6e-3064-4384-88f0-d1ef2d4766a
    name: oauth-security-definition
    version: 1.0.0
    description: OAuth2 Provider not defined.
    given:
      $.securityDefinitions[*]
    severity: error
    then:
      field: type
      function: pattern
      functionOptions:
        match: ^oauth2$

Save and publish the ruleset so it becomes available for validation scans in the provider org.

Bonus: adidas publishes its OpenAPI (OAS) Spectral rules publicly — a useful reference when designing your own org checks: adidas/api-guidelines .spectral.yml.

Step 2 — Select the Rules for Validation

Start Validate APIs with ruleset. On Select rules, choose the five rules from mybank-oauth-check — all of them in this example.

Continue to Select APIs and pick the API you want to test — here, balance-transfer-api:1.0.0.

Step 3 — Run the Scan and Read the Results

Open View results. Against a non-compliant definition, the scorecard returns error-level findings tied to specific rules.

In this run, balance-transfer-api:1.0.0 fails three rules in mybank-oauth-check:1.0.0:

1. oauth-provider-registered — no approved myBank OAuth2 provider reference
2. oauth-required-scopes-defined — no explicit scopes declared
3. oauth-security-definition — OAuth2 provider / type not defined as required

Each row tells you the severity, message, rule name, ruleset version, and API — enough to fix the OpenAPI definition without guessing.

Step 4 — Fix the API and Re-test

Update the API definition so it satisfies every rule, then re-run the same validation:

1. Add a security definition with “type”: “oauth2”.
2. Set x-ibm-oauth-provider to a value matching the approved provider id (for example inEdgeOAuth2Provider-1.0.0-a1b2).
3. Declare at least one scope under scopes.
4. Use a non-implicit flow (for example accessCode / authorization code).
5. Remove any operation-level security: [] overrides.

Re-validate with the same five rules selected. A clean scorecard means the contract now meets org OAuth2 policy and is ready for the next publish gate.

Key Takeaways

• A ruleset encodes OAuth2 policy once; every scan reuses the same checks.
• Select rules → Select APIs → View results is the fastest loop for testing a new ruleset against a real API.
• Error messages map 1:1 to rule names, so fixes are specific (x-ibm-oauth-provider, scopes, type, flow, operation security).
• Catching failures on balance-transfer-api before publish keeps non-compliant definitions out of the catalog.

What changed

Same policies still matter — invoke, map, switch, security, transforms. Same Product / Plan / Catalog lifecycle. What changed is packaging: the flow is no longer trapped inside one API file.

The one idea to keep

What used to be “the assembly on this API” is now something you attach:

policy-seq → $ref: namespace:policy-sequence-name:version

Same Orders flow (invoke backend → map response) still exists. In Designer it sat under assembly.execute. In Studio it lives in a policy-sequence file and the API just references it. Reuse without copy-paste.

Old: one API YAML (Designer)

# orders-1.0.0.yaml — contract + assembly together
openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      # ... parameters & responses ...

x-ibm-configuration:
  assembly:
    execute:
      - invoke:
          title: invoke-orders-backend
          target-url: $(orders-backend-url)/orders/$(request.parameters.orderId)
      - map:
          title: map-order-response
          inputs:
            backend:
              variable: message.body
          outputs:
            response:
              variable: message.body
          actions:
            - set: response.orderId
              from: backend.id
            - set: response.status
              from: backend.orderStatus

New: api-spec + policy sequence (Studio)

1. Clean OpenAPI (api-spec)

# orders-api-spec.yaml
openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      # ... parameters & responses ...

2. Policy sequence (the old assembly)

# orders-backend-flow.yaml
kind: PolicySequence
metadata:
  name: orders-backend-flow
  namespace: orders
  version: 1.0.0
spec:
  execute:
    - invoke:
        title: invoke-orders-backend
        target-url: $(orders-backend-url)/orders/$(request.parameters.orderId)
    - map:
        title: map-order-response
        inputs:
          backend:
            variable: message.body
        outputs:
          response:
            variable: message.body
        actions:
          - set: response.orderId
            from: backend.id
          - set: response.status
            from: backend.orderStatus

3. API metadata attaches it

# orders-api.yaml
kind: api
metadata:
  name: orders
  namespace: orders
  version: 1.0.0
spec:
  api-spec: orders-api-spec.yaml
  policy-seq:
    $ref: orders:orders-backend-flow:1.0.0

Same invoke → map. Different packaging — and that sequence can be reused on other APIs or scopes.

Why IBM moved this way

Studio is built for API-as-code, shared governance, multi-gateway authoring (DataPower API Gateway, Nano, webMethods), DevOps ownership, and AI/agent tooling. Structured assets beat one opaque mega-YAML.

Day-1 remap: create a project → import OpenAPI → create a policy sequence → attach at API level → try scope-level → Tryout/publish. Start in Form View if you loved the canvas; switch to Code View once $ref clicks. And do not assume old v10 APIs drop unchanged onto Nano or webMethods.

If you are still asking “where did Assembly go?” — reframe it. Assembly became a reusable object. Designer is deprecated. The ideas are not.

In IBM API Connect, you can define named assembly rate limits on an API plan and then consume the right limit at runtime based on a value from the request — in my case, the opname header. Here is the pattern I use.

The Problem

A single endpoint handles multiple logical operations. Clients send an opname header (create, update, or delete) to indicate what they want to do. Each operation has a different cost profile:

A one-size-fits-all rate limit either blocks legitimate light traffic or lets expensive operations through too easily.

Step 1 — Define Named Limits on the API Plan

In the API product plan, open Assembly rate limits and create one named limit per operation. The Cost field is the weight consumed per request; Per and Unit define the refill window.

In my setup:

• create — cost 5, 1 per minute
• update — cost 10, 1 per minute
• delete — cost 20, 1 per minute

These names (create, update, delete) are the keys the assembly will reference later. Keeping names aligned with the header values avoids mapping logic in the gateway.

Step 2 — Branch in the Assembly with a Switch

Add a switch policy at the top of the assembly (after authentication, before invoke). Each case matches request.headers.opname and routes to a dedicated ratelimit policy.

The four branches:

1. request.headers.opname = “create” → ratelimit (create)
2. request.headers.opname = “update” → ratelimit (update)
3. request.headers.opname = “delete” → ratelimit (delete)
4. Otherwise → throw (reject unknown operations)

The Otherwise branch is important. Without it, requests with a missing or invalid opname would skip rate limiting entirely and still reach the backend.

Step 3 — Configure Each Ratelimit Policy

Each ratelimit policy on a switch branch uses the same settings pattern; only the Rate limit name changes to match the plan definition.

Key fields:

Repeat this policy three times — one per switch case — changing only the rate limit name.

How It Works End to End

1. Client calls the API with header opname: create.
2. The switch matches the create branch.
3. The ratelimit policy consumes 5 tokens from the create bucket defined on the plan.
4. If tokens remain, the request continues to invoke; if not, API Connect returns 429 Too Many Requests.

A delete call on the same endpoint consumes from the delete bucket at cost 20, so heavy operations are throttled more aggressively even though the URL is identical.

Example Request

curl -X POST "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "opname: update" \
  -d '{"orderId": "ORD-1001", "status": "shipped"}'

With opname: update, the gateway hits the update branch and consumes from the update rate-limit bucket.

Assembly Snippet (YAML)

For teams managing APIs as code, the same logic in OpenAPI extension / assembly YAML looks like this:

assembly:
  execute:
    - switch:
        title: switch
        case:
          - condition: $(request.headers.opname) = 'create'
            execute:
              - ratelimit:
                  title: ratelimit-create
                  source: plan-named
                  rate-limits:
                    - name: create
                      operation: consume
          - condition: $(request.headers.opname) = 'update'
            execute:
              - ratelimit:
                  title: ratelimit-update
                  source: plan-named
                  rate-limits:
                    - name: update
                      operation: consume
          - condition: $(request.headers.opname) = 'delete'
            execute:
              - ratelimit:
                  title: ratelimit-delete
                  source: plan-named
                  rate-limits:
                    - name: delete
                      operation: consume
        otherwise:
          - throw:
              title: throw
              message: "Invalid or missing opname header"
              name: InvalidOperation
    - invoke:
        title: invoke
        target-url: $(target-url)

Adjust the throw message and fault name to match your API’s error contract.

Testing Tips

• Verify each branch — send requests with each opname value and confirm the correct limit is hit in analytics.
• Exhaust one bucket — flood create until you get 429; confirm update still works on the same client credentials.
• Test the Otherwise path — omit opname or send opname: patch and confirm the throw policy fires before invoke.
• Watch plan changes — if you rename a limit on the plan, update every matching ratelimit policy in the assembly.

Key Takeaways

• Named assembly rate limits on the plan let you define multiple weighted buckets in one subscription.
• A switch on request headers selects the right bucket without duplicating APIs or routes.
• plan-named + consume ties assembly policy to plan configuration — change limits in the product without redeploying assembly logic.
• Always add an Otherwise branch so malformed requests cannot bypass throttling.

This pattern works well for multiplexed endpoints, legacy systems that overload a single URL, and any API where operation cost varies but the routing surface stays flat.