Skip to main content

Versioning and compatibility

The version is in the path: https://api.nasam.co/mm-api/v1. Within v1 the API changes only by addition, so an integration built against v1 keeps working.

What can change within v1​

  • New operations.
  • New optional request parameters and body fields.
  • New response fields.
  • New values in an existing enum, such as a new order status or marketplace.
  • New webhook event types.

What your client must do​

  • Ignore response fields you do not recognise. Do not fail on extra properties; configure generated clients and schema validators to allow them.
  • Tolerate unknown enum values. Map a status, type or reason you do not recognise to a fallback such as "other" instead of failing, and log it so you can add handling later.
  • Ignore webhook event types you do not handle, and still return 2xx.
  • Send only documented request fields. A field the operation does not declare is rejected.

What never changes within v1​

Removing or renaming an operation, parameter or field; changing a field's type; making an optional request field required; and removing an enum value. Nasam checks every contract change against the released v1 before it ships.

When v2 ships​

A breaking change ships as a new version, /mm-api/v2, alongside v1. v1 keeps working for a migration period. During that period every v1 response carries:

  • Deprecation, the date v1 was deprecated.
  • Sunset, the date after which v1 stops answering.

Watch for these headers in your logs; they are your signal to plan the move. Migration notes for each changed operation are published on this site.

Stay current​

The OpenAPI 3.1 file is the v1 contract. Regenerate clients from it when you need a new field or operation; a client generated from an earlier copy keeps working.