Skip to content

Migration Decision Matrix

Not sure which API to use? Use this decision tree to find the right path for your use case.

Quick decision tree

Start here: What are you trying to do?

1. I'm a new user or team starting fresh

→ Use Aleph V2 (Orders API)

  • Modern, unified interface
  • Single learning curve
  • Best for greenfield projects
  • Next step: Aleph V2 Quickstart

2. I'm using V1 Tasking API and want to stay up-to-date

→ Migrate to Aleph V2 Orders API

3. I'm a V1 Archive API user

→ Consider migrating to Aleph V2 Orders API

  • Archive ordering moves from web-only to API-first
  • Any processing level available (not just L1B)
  • Automatic clipping and stitching
  • Monthly consumption tracked as Orders
  • See Archive Products (V2)
  • Next step: Archive Consumption (V1 to V2) to understand the mapping

4. I have a large production system with V1 integrations

→ Staged migration recommended

  • Phase 1: Monitor existing V1 orders via V2 API (read-only)
  • Phase 2: New projects in V2 while keeping V1 running
  • Phase 3: Full migration when V2 is stable
  • Next step: Adoption Guide - Staged strategy

5. I need specific features only in V1

→ Stay with V1, but plan for migration

  • Confirm with support that your feature is not planned for V2
  • Use Phase 1 (monitoring) to get familiar with V2 model
  • Revisit quarterly as V2 evolves
  • Next step: Contact support with your specific needs

Detailed decision matrix by use case

Archive workflows

Use case V1 solution V2 solution Recommendation
Discover and download L1B tiles STAC API + Delivery API Archive Explorer + V2 API V2 for web UI; both APIs supported
Order custom processing level (L1C, L1D) Web UI only V2 API + web UI Migrate to V2 (API support added)
Clip archive to custom area Manual (post-download gdalwarp) Auto-clipped in V2 order Migrate to V2 (huge UX improvement)
Track archive orders Manual / spreadsheet V2 Orders API + events Migrate to V2 (full observability)
Monthly consumption reporting Tile counting script Deliverables endpoint Migrate to V2 (automated)

Tasking workflows

Use case V1 solution V2 solution Recommendation
POI tasking (single point) Analysis API + Tasking API V2 Orders API (TSKPOI-M) V2 is direct replacement
AOI tasking (polygon) Analysis API + Tasking API V2 Orders API (TSKARE-M) V2 is direct replacement
Rush tasking Tasking API (product_id) V2 Orders API (TSKRSH-M.NN.NN) V2 is direct replacement
Monitor task status Tasking API (limited visibility) V2 Orders API (rich events) V2 has better visibility
Opportunity preview before tasking Analysis API V2 Orders API (same capabilities) Both supported; V2 simpler

Cross-product workflows

Use case V1 solution V2 solution Recommendation
Mix archive + tasking in one system Multiple APIs (complex) V2 Orders API (unified) Migrate to V2 (huge simplification)
Unified consumption tracking Manual aggregation V2 Deliverables endpoint Migrate to V2 (automated)
Single order tracking dashboard Custom (per API) V2 Orders API (unified) Migrate to V2 (built-in)

Migration checklist

Before you migrate

  • ☐ Understand your current V1 usage: which APIs, which products, which features
  • ☐ Identify integration points: where V1 APIs are called in your code
  • ☐ Define success criteria: what V2 must support for your team
  • ☐ Plan timeline: when you want to be fully migrated
  • ☐ Estimate effort: how many code changes, how many test cycles

Phase 1: Read-only monitoring (low risk)

  • ☐ Get Orders API credentials and access
  • ☐ Write test queries: GET /orders?task_id={your_v1_task_id}
  • ☐ Verify you can see your existing V1 orders as V2 Orders
  • ☐ Build monitoring dashboard using Deliverables endpoint
  • ☐ Keep all V1 production code running unchanged

Phase 2: New projects in V2 (medium risk)

  • ☐ Start 1–2 new projects using V2 API
  • ☐ Rewrite code using Orders API patterns
  • ☐ Test against V2 specs and examples
  • ☐ Run parallel with V1 production
  • ☐ Monitor and iterate

Phase 3: Full migration (production)

  • ☐ Migrate existing integrations one at a time
  • ☐ Update all API calls to V2 patterns
  • ☐ Retire V1 API calls gradually
  • ☐ Monitor for issues; rollback plan ready
  • ☐ Sunset V1 code when stable

Support and questions

What does your team need?