Skip to content

Latest commit

 

History

History
114 lines (87 loc) · 7.44 KB

api_notes.md

File metadata and controls

114 lines (87 loc) · 7.44 KB

API Notes

A plain-language guide for site users lives at /api-guide (resources/views/pages/api-guide-tw.blade.php). Keep it in step with this file and routes/api.php.

API Endpoints

Documentation Generation

  • Generated using Swagger js referencing public/postman folder.

Usage

  • Currently requires a basic auth username and password to access the API.
  • You can also request a user token to access the API.

Authenticaion

  • You can query the API using basic auth or a user token.
  • To authenticate using basic auth, include the Authorization header with the value Basic base64(username:password).
  • To authenticate using a user token, include the Authorization header with the value Bearer your_user_token.
  • To acquire a user token, call POST /api/tokens/create with basic auth credentials. When requesting a token, include in the body a token_name key with the desired name for the token.

Rate Limits

All /api/* routes go through the api rate limiter (RouteServiceProvider::configureRateLimiting):

Caller Limit Keyed by
Authenticated (basic auth or bearer token) 240 requests / minute user id
Anonymous (e.g. /api/search, /api/calendar-events) 120 requests / minute IP address
POST /api/{events,entities,series}/{id}/photos/from-url 20 requests / minute, on top of the general limit user id
Failed basic auth attempts 20 failures / minute IP address
  • Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with a Retry-After header (seconds).
  • After 20 failed basic auth attempts from one IP, basic auth from that IP is refused with 429 for the rest of the minute, even with the correct password. Successful logins don't count. This applies to auth.either routes and POST /api/tokens/create.
  • AuthenticateEither implements AuthenticatesRequests so Laravel's middleware priority runs it before ThrottleRequests. That's what lets the limiter see the user. Don't remove the interface, or every basic auth caller falls back to the per-IP limit.
  • Counters live in the default cache store (CACHE_DRIVER), so they're per server unless the cache is shared.

Email Verification

  • After registration, users will receive a verification email with a signed URL.
  • The email verification endpoint is: GET /api/email/verify/{id}/{hash}
  • This endpoint requires a valid signed URL (generated by the system) with the user ID and email hash.
  • The endpoint will return a JSON response with a success or error message.
  • No authentication is required for this endpoint, but it requires a valid signature and hash.
  • Creating or updating content needs a verified email, as on the web (#2314). An unverified account gets 403 with {"message": "Your email address is not verified."} from the create, update and photo routes of events, entities (and their contacts, links, locations and photos), series, tags, threads, posts, blogs, links and locations. Nothing is written.
  • Reads, follow/unfollow, attend and POST /api/tokens/create still work for an unverified account, so a client can sign in and show a "verify your email" state.
  • The 403 is JSON even without an Accept: application/json header (App\Http\Middleware\EnsureEmailIsVerified); web routes still redirect to the verification page.
  • WriteRouteAuthorizationTest::UNVERIFIED_ALLOWED lists the API write routes that don't need a verified email. A new API write route must refuse an unverified user unless it's added there.

Filtering Lists

You can apply filters to routes using the following:

  • To filter by a specific field, use the field name as the key and the value as the value.
    • Example: GET /api/events?filters[name]=Event Name
  • To order by a specific field, use the field name as the key and the value as the value.
    • Example: GET /api/events?sort=model.property&direction=asc
  • To filter events by multiple tags you can provide a comma separated list or repeat the filters[tag] parameter.
    • GET /api/events?filters[tag]=music,art
    • When you need events that contain all of the supplied tags, use filters[tag_all] instead.
    • GET /api/events?filters[tag_all]=music,art

Tags on Create and Update

tag_list on the event, entity, series, post, blog and thread create/update endpoints accepts a mix of existing tag ids and free-text names.

  • Ids are matched by primary key.
  • Names are slugged and matched to an existing tag by slug, so "diy", "DIY" and "Diy" all resolve to the existing Diy tag.
  • A tag is created only when no id or slug matches. Sending an existing tag's name never creates a duplicate.
  • PUT /api/events/{event} with tag_list is a full sync (a missing key detaches all tags); PATCH only syncs when tag_list is present.

Events with Several Dates

A short-run event (a play, a festival weekend) keeps its first date in start_at and its other dates in showings. An event with one date has an empty showings.

POST /api/events
{ "name": "...", "start_at": "2027-03-01 20:00:00",
  "showings": [
    { "start_at": "2027-03-04 19:00:00" },
    { "start_at": "2027-03-06 14:00:00", "end_at": "2027-03-06 16:00:00", "door_at": "2027-03-06 13:30:00" }
  ] }
  • Each showing must start after start_at, no two may share a start, and there can be at most 60.
  • PUT replaces the showings with what it sends (none removes them all); PATCH only touches them when showings is present.
  • Responses carry showings, last_start_at (the final date's start) and next_start_at (the first date still to come, else start_at).
  • filters[start_at] and /api/events/by-date/... match an event on any of its dates, and sorting by events.start_at with a start filter orders by each event's next date in range.

Attaching Photos by URL

POST /api/events/{id}/photos (and the entity / series equivalents) take a multipart file upload. Each has a sibling that accepts a public https URL instead, for callers that cannot hold the bytes themselves (browser automation blocked by CORS, sandboxed agents, importers):

POST /api/events/{id}/photos/from-url
POST /api/entities/{id}/photos/from-url
POST /api/series/{id}/photos/from-url

{ "url": "https://example.com/flyer.jpg" }

Behaviour matches the upload endpoint: same ownership rule (owner or admin), first photo becomes primary, followers are notified on an event's first photo, 201 with the photo's API representation. The differences are the guards on the fetch itself, all of which return 422 with a message:

  • https only, on every hop; at most 3 redirects.
  • The host must resolve to a public address. Loopback, link-local (including cloud metadata), RFC1918 / ULA and other reserved ranges are refused, and every redirect target is re-checked.
  • 5 MB cap (the same as the web uploader), enforced while downloading rather than from Content-Length.
  • The downloaded bytes are sniffed and must be a jpg, jpeg, png, gif or webp image, regardless of the URL extension or Content-Type header.
  • 10 s connect / 20 s total timeout.

The stored file name is derived from the last path segment of the final URL, sanitized and given the sniffed extension. The route is rate limited to 20 requests per minute per user, separately from the rest of the API.

curl -u user:pass -H 'Accept: application/json' \
  -d 'url=https://example.com/flyer.jpg' \
  https://arcane.city/api/events/123/photos/from-url