Running & Testing Locally

You have installed Exowpee and want to see it answer. This page starts the application, signs in, selects a company, reads a list and makes a write. For the same calls against the hosted API, see the Quickstart.

1. Start the application

The project runs in Docker; there is no local composer or php to rely on.

docker compose up -d
docker compose exec app php artisan migrate

If you did not seed the database during installation, create the permissions and built-in profiles before the first sign-up. Without them, signing up answers 500 (“templates and their exact permissions must be discovered before owner bootstrap”):

for guard in api agent client-api client-agent organization-api organization-agent; do
  docker compose exec app php artisan permissions:discover --guard=$guard
done

The API is then at http://localhost:8000/v1, the port that nginx serves in the compose stack. Signing in needs a member whose email address is verified. Signing up goes through Check an email address, Sign up with a company and the verification link sent by email, so the mail settings of your environment must deliver or log that email. The address must be real: its domain is checked, so name@example.com is refused. See Sign up and sign in. Use docker compose exec app php artisan config:show mail to see where mail goes. Do not copy the .env file anywhere.

curl -X POST http://localhost:8000/v1/auth/user/login \
  -H "Content-Type: application/json" \
  -d '{"username": "you@example.com", "password": "your-password"}'

The answer holds auth.access_token. Keep it:

export TOKEN="paste the access_token here"

The type in the path (user here) also accepts agent, client, client_agent, organization and organization_agent. Sign in lists the fields each type needs and the refusals. The route allows 5 attempts per minute.

4. Select a company

A member’s token has no company selected yet, so company routes answer 403 until a profile assignment is chosen. Take an id from user.user_profiles in the sign-in answer, or from View my account, and switch to it:

curl http://localhost:8000/v1/auth/me -H "Authorization: Bearer $TOKEN"
curl -X POST http://localhost:8000/v1/auth/switch-user-profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_profile_id": "<id from user_profiles>"}'

Switch company profile answers like sign-in. Replace TOKEN with the new auth.access_token; the previous token stops working.

5. Read

curl "http://localhost:8000/v1/catalog/categories?per_page=5" -H "Authorization: Bearer $TOKEN"

View my account shows who you are in the current space. List categories answers {data, meta: {per_page, next_cursor, prev_cursor}}. It needs the categories.list permission.

6. Write

curl -X POST "http://localhost:8000/v1/catalog/categories?response=resource&fields=id,title" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Cement", "sort_order": 1}'

Create a category answers 204 without ?response=resource, like every migrated POST, PUT and PATCH. With it, the answer is the created category with status 201, and fields keeps only the keys you name. include adds related objects the same way. A refused call answers with a JSON body: 403 with status_code and message, 422 with message and, for invalid fields, errors. The Quickstart lists them.

7. Run the checks

docker compose exec app php -d memory_limit=1G artisan test --filter=NameOfYourTest
docker compose exec app ./vendor/bin/pint

Run only the tests your change touches. The generated API document is served at http://localhost:8000/docs/api by Scramble.

Where next

Project structure shows where code lives.
Open your shop on Exowpee is a full setup in order.
The big picture explains the model.

Start here

Concepts

Reference

Running & Testing Locally

1. Start the application

4. Select a company

5. Read

6. Write

7. Run the checks

Where next

​1. Start the application

​2. Have an account that can sign in

​3. Sign in

​4. Select a company

​5. Read

​6. Write

​7. Run the checks

​Where next

1. Start the application

2. Have an account that can sign in

3. Sign in

4. Select a company

5. Read

6. Write

7. Run the checks

Where next