Migrate Existing API Assets into Glubean

You do not need to rewrite every collection, spec, or legacy suite by hand.

But you also should not treat migration as a blind format conversion job.

The right workflow is:

1. start inside a real Glubean project
2. use the glubean skill
3. scan the source assets first
4. lock one good pattern
5. batch-convert from that pattern

That works for Postman, Apifox, OpenAPI, .http files, cURL snippets, and legacy test code.

For stable API promises, migrate toward contracts and workflows when possible. Use raw test() for migration slices, custom setup, diagnostics, or behavior that needs unrestricted TypeScript.

The goal is not “Postman JSON becomes one test file.” The goal is one set of Glubean assets: executable contracts for durable promises, workflows for lifecycle behavior, and raw test() checks where unrestricted TypeScript is the right tool.

npx glubean init

Use the Glubean skill for migration

Do not approach migration with a generic “convert this collection” prompt.

Install and use the Glubean skill first:

npx skills add glubean/skill
npx glubean config mcp

Then invoke the skill in chat when your editor supports it:

/glubean help me migrate these API assets into Glubean contracts, workflows, and tests

Why this matters:

• the skill tells the agent to read project structure first
• it routes migration work through a migration-specific workflow instead of generic code generation
• it nudges the agent toward contracts/workflows when durable behavior should become source of truth, and toward configure(), builder-style raw tests, types, schemas, and CI-safe structure when raw test() is the better fit
• it is much more likely to stop and ask when auth or secret mapping is unclear

If your AI tool does not support slash commands, still mention the skill explicitly in the prompt:

Use the glubean skill and follow a phased migration workflow.

What migration really means

Migration is not “translate this JSON into code.”

It is a verification architecture task:

• keep the useful request definitions you already have
• classify which requests are isolated vs stateful
• choose one auth and config approach
• decide file grouping and assertion depth
• convert one representative slice first
• then reuse that pattern across the rest of the suite

If you skip those decisions, bulk conversion usually creates a large pile of weak assets: contracts that do not describe real promises, workflows that do not prove useful lifecycles, and tests that only check status codes.

Supported source formats

These sources are all useful, but in different ways:

• Postman and .http files are strong request seeds
• OpenAPI is strong for grouping and schema hints
• legacy test code is strong for business intent and assertion history
• docs and notes are strong for explaining why the API behaves a certain way

What AI can do well

AI is good at converting:

• methods, URLs, headers, query params, and bodies
• placeholders into vars and secrets
• source grouping hints into candidate file plans
• old assertions into Glubean assertion syntax
• repeated setup into shared configure() clients or helper flows

AI is not good at guessing:

• auth strategy
• which values are secrets vs public config
• whether two requests belong in one contract workflow, one builder-style raw test, or separate checks
• whether status-only assertions are enough
• what custom pre-request scripts were really doing

Those are the points where the agent should stop and ask.

Guide the migration phase by phase

The user guidance should be explicit and phased:

1. use the glubean skill
2. ask for a scan-only migration phase
3. confirm auth before any code — this is the most common migration failure
4. lock minimal project shape (config, vars/secrets, grouping)
5. build one representative slice to validate that shape
6. freeze reusable style from the slice, then batch-convert
7. run and tighten the migrated assets

The first prompt should produce a plan, not files.

Recommended migration path

npx skills add glubean/skill
npx glubean config mcp

/glubean I want to migrate existing API assets into Glubean contracts, workflows, and tests.
Use a phased workflow and do not generate files yet.

Sources:
- Postman collection: /path/to/collection.json
- OpenAPI spec: ../api/openapi.yaml
- Legacy tests: ../backend/tests/api/

/glubean do a migration feasibility scan only. Do not generate files yet.

Read the Glubean project first (package.json, GLUBEAN.md, tests/, config/).

Then read these source assets (do not copy them into the project):
- [paths to Postman / Apifox / OpenAPI / .http / legacy tests]

Return:
1) source inventory
2) what can be converted safely
3) what needs manual decisions
4) open questions and blockers
5) proposed file plan
6) proposed auth + vars/secrets mapping
7) one representative slice to implement first

If auth, secret classification, or pre-request logic is unclear, stop and ask.

/glubean I've reviewed the scan. Here is the auth and project shape:
- Auth: [bearer / API key / OAuth / none]
- Secrets: [list what goes in .env.secrets]
- Config: [shared client location]
- Grouping: [by resource / workflow / tag]

Lock this shape and implement only the representative slice.

/glubean the representative slice is approved.
Freeze the migration style from it, then convert the next group only: [folder/tag/module].
Stop after that group and summarize manual follow-up items.

/glubean run and review the migrated files for this phase.
Fix real failures, tighten weak assertions, and keep unresolved logic as explicit TODOs.

How to map old assets to Glubean

Postman

Translate carefully:

• env variables -> vars or secrets
• folder structure -> grouping hints only
• pm.test(...) -> Glubean assertions
• collection or local variables -> builder state or shared setup
• pre-request scripts -> shared auth/setup or manual follow-up

Do not mechanically port pm.* helpers line by line.

Apifox

Apifox usually works best when exported as:

• OpenAPI for schema-aware planning
• Postman when example requests are clearer than the spec

If both exist, the agent should compare them instead of trusting one blindly.

OpenAPI / Swagger

OpenAPI is useful for:

• operation grouping
• operation IDs
• request and response shape
• deprecated endpoint filtering

It is weaker for runtime auth behavior and business-rule assertions, so those usually need repo context or user input.

REST Client and cURL

Treat these as strong request seeds:

• preserve request shape
• improve assertion depth
• merge duplicated setup into shared config
• convert ad-hoc examples into stable regression tests

Legacy test code

This is often the best source for real test intent.

Keep:

• scenarios
• business assertions
• setup and teardown meaning

Do not keep:

• framework-specific fixtures
• custom client wrappers unless they encode essential business behavior
• assertion syntax that hides the real expectation

Prompt templates

Use the feasibility scan first. Then use a focused follow-up prompt with the skill.

/glubean I have a Postman or Apifox export at [path].

Use the approved migration plan.
Implement only one group first.

Requirements:
- create or reuse a shared configured client
- classify secrets vs vars explicitly
- use `workflow()` for durable lifecycle promises and builder-style raw tests
  only for custom runtime sequences
- keep durable isolated requests as `contract.http` cases and ad-hoc checks as
  separate `test()` exports
- add status + key field assertions
- mark unclear script behavior with TODO instead of guessing

Return:
1) shared config changes
2) one migrated Glubean asset file
3) short manual follow-up items

/glubean I have an OpenAPI spec at [path].

Use the approved migration plan.
Implement only one representative tag first.

Requirements:
- group by tag unless the repo conventions suggest a better grouping
- use operationId as the default test id when it is stable
- create shared config first
- add schema validation where the shape is trustworthy
- stop and ask if auth or error semantics are unclear

/glubean I have existing API tests or .http files at [path].

Use them as migration sources, not as code to translate literally.
Implement one representative slice first.

Requirements:
- preserve the scenario intent
- move repeated request config into a shared client
- convert setup/cleanup into `workflow()` or builder-style raw tests only when
  state truly carries across steps
- prefer contracts for durable API promises, workflows for reusable lifecycles,
  and raw `test()` for custom runtime behavior
- keep strong assertions from the old suite
- replace framework-specific helpers with Glubean patterns

Shared client baseline

Prefer a configured client over ad-hoc request setup in every file.

// config/api.ts
import { configure } from "@glubean/sdk";
 
export const { http: api, vars, secrets } = configure({
  vars: { baseUrl: "{{BASE_URL}}" },
  secrets: { apiToken: "{{API_TOKEN}}" },
  http: {
    prefixUrl: "{{BASE_URL}}",
    headers: {
      Authorization: "Bearer {{API_TOKEN}}",
      Accept: "application/json",
    },
  },
});

Then use the shared client from contracts, workflows, or raw tests:

import { test } from "@glubean/sdk";
import { api } from "../config/api";
 
export const listUsers = test("list-users", async (ctx) => {
  const res = await api.get("users");
  ctx.expect(res).toHaveStatus(200);
});

Quality checklist

• the user was told to use the glubean skill, not a generic prompt
• migration happened inside a real Glubean project
• the first round was a scan, not bulk file generation
• auth was explicitly confirmed before any code was generated
• minimal project shape (config, vars/secrets, grouping) was locked before the slice
• one representative slice was reviewed before expansion
• reusable style was frozen from the slice before batch work
• durable endpoint behavior became contracts where possible
• stateful sequences use workflow() or builders only when needed
• write-path assets include reliable cleanup or a documented cleanup policy
• critical endpoints have more than status-only assertions
• unclear script logic is marked and isolated instead of guessed

Known limits

These usually need manual follow-up:

• custom signing or encryption scripts
• token refresh or browser-based login flows
• implicit state shared across folders or files
• poorly documented business rules
• conflicting evidence between collections, specs, and runtime behavior

That is normal. Success means the migration becomes structured, reviewable, and consistent, not that every source detail is translated literally.

What next?

• Quick Start — initialize the project and install the extension
• Generate with AI — prompt more effectively
• Writing Tests — learn the test shapes and project layout