apiary skip if exists resumability

=====================================

Apiary's unique approach to resumable documentation involves using skip-if-exists directives in Drip scripts to ensure that crashes don't lose work. This feature is particularly useful for founders who command in English and rely on Apiary to generate code.

What is Skip If Exists?

Skip If Exists is a directive used in Drip scripts to check if a resource already exists before creating it. This prevents duplicate resources from being created, which can lead to errors or inconsistencies in the generated code.

Example Code

Drip:
  - name: Create User
    type: POST
    path: /users
    skip-if-exists: true

In this example, the skip-if-exists directive is set to true, which tells Apiary to check if a user with the same ID already exists before creating a new one.

How Does It Work?

When a Drip script encounters a resource that already exists, it will skip creating the duplicate resource and continue executing the next steps in the script. This ensures that crashes don't lose work, as all progress is preserved.

Example Use Case

Drip:
  - name: Create User
    type: POST
    path: /users
    body:
      name: John Doe
      email: johndoe@example.com

  - name: Create Order
    type: POST
    path: /orders
    skip-if-exists: true
    body:
      user_id: $userId

In this example, the first step creates a new user with ID 123. If the user already exists, the second step will skip creating a duplicate order for that user.

Benefits of Skip If Exists Resumability

1. Crash Recovery: With skip-if-exists resumability, crashes don't lose work. Apiary preserves all progress and resumes from where it left off.
2. Improved Reliability: By preventing duplicate resources from being created, skip-if-exists reduces errors and inconsistencies in the generated code.

Tips for Using Skip If Exists

1. Use skip-if-exists directives judiciously to avoid unnecessary checks and improve performance.
2. Combine skip-if-exists with other Drip script features, such as conditional logic and loops, to create complex workflows.

Related/Sources:

• Apiary Documentation: Drip Scripts
• Apiary Blog: Resumable Documentation