search

cognitect-labs / vase

Data driven microservices
Eclipse Public License 1.0
375 stars 41 forks source link

your_first_api.md suggested changes #29

Closed mchampine closed 7 years ago

mchampine commented 7 years ago

Description

Documentation for creating your first API in https://github.com/cognitect-labs/vase/blob/master/docs/your_first_api.md needs some edits

  1. The vase.api/schemas value is inconsistent. The first 2 instances show:

:vase.api/schemas [:account/item]

but after that it changes to:

:vase.api/schemas [:accounts/user]

  1. The schema description is confusing. It starts with a cookbook process saying "Start by clearing out the current value of :vase/norms and replace it with this:
     :vase/norms
      {:your-first-api/accounts {}
      }

But after that ":your-first-api/accounts" is replaced with 2 schemas: :accounts/item and :accounts/user, and there is no schema ending in /accounts. That makes for confusion in trying to reconcile the initial edit instructions with the followup snippets. It would be really helpful to have an "end result" edn example available.

  1. This is probably obvious and planned, but it wold be help to have curl examples at each stage, esp. POST examples - since it's not obvious that you need to use "payload" (as mentioned in a recent issue report).

Thanks, this is great stuff! I'm enjoying learning vase. Hope this is helpful. Wasn't sure if you'd prefer pull requests or issue reports for these doc changes.

mtnygard commented 7 years ago

Thanks for the bug reports and suggestions. The errors were definitely mine. Will fix shortly.