BradNut/graphbrainz
1
0
Fork 0
mirror of https://github.com/BradNut/graphbrainz synced 2025-09-08 17:40:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update README.md

Browse source
This commit is contained in:
Brian Beck 2017-11-19 10:52:19 -08:00 committed by GitHub
parent d8b8de2dce
commit 37e872b1e7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
docs/extensions/README.md
View file

@ -178,29 +178,28 @@ consistency with GraphBrainz and the built-in extensions. Here are some tips
for writing a good extension: for writing a good extension:
* If you need to make HTTP requests, using a [Client][] subclass will get you * If you need to make HTTP requests, using a [Client][] subclass will get you
rate limiting, error handling, and a Promise-based API for free. rate limiting, error handling, retrying, and a Promise-based API for free.
* Default to following the rate limiting rules of any APIs you wrap. If there * Default to following the rate limiting rules of any APIs you use. If there
are no guidelines on rate limiting, consider playing nice anyway and limiting are no guidelines on rate limiting, consider playing nice anyway and limiting
your client to around 1 to 10 requests per second. your client to around 1 to 10 requests per second.
* Use a [DataLoader][dataloader] instance to batch and cache requests. Even if * Use a [DataLoader][dataloader] instance to batch and cache requests. Even if
the data source doesn’t support batching, it will dedupe in-flight requests the data source doesn’t support batching, DataLoader will help by deduping
for the same key, preventing extra requests before the response has been in-flight requests for the same key, preventing unnecessary requests.
cached.
* Use a configurable cache and make sure you aren’t caching everything * Use a configurable cache and make sure you aren’t caching everything
indefinitely by accident. The `cacheMap` option to DataLoader is a good place indefinitely by accident. The `cacheMap` option to DataLoader is a good place
to put it. to put it.
* Get as much configuration from environment variables as possible, so that * Get as much configuration from environment variables as possible so that
people can just run the standalone server instead of writing any code. If users can just run the standalone server instead of writing any code. If you
you need more complex configuration, use a single object on the `options` need more complex configuration, use a single field on the `options` object
object as a namespace for your extension’s options. as a namespace for your extension’s options.
* Don’t be afraid to rename fields returned by third-party APIs when translating * Don’t hesitate to rename fields returned by third-party APIs when translating
them to the GraphQL schema. Consistency with GraphQL conventions and the them to the GraphQL schema. Consistency with GraphQL conventions and the
GraphBrainz schema is more desirable than consistency with the original API GraphBrainz schema is more desirable than consistency with the original API
being wrapped. Some general rules: being used. Some general rules:
* Match type names to the service they’re coming from (e.g. some services use * Match type names to the service they’re coming from (e.g. many services use
the words “album” and “track”), but match scalar field names to their the words “album” and “track” and the type names should reflect that), but
MusicBrainz equivalents when possible (e.g. `name` for artists but `title` match scalar field names to their MusicBrainz equivalents when possible
for releases and recordings). (e.g. `name` for artists but `title` for releases and recordings).
* Use camel case naming and capitalize acronyms (unless they are the only * Use camel case naming and capitalize acronyms (unless they are the only
word), e.g. `id`, `url`, `artistID`, `pageURL`. word), e.g. `id`, `url`, `artistID`, `pageURL`.
* If it’s ambiguous whether a field refers to an object/list vs. a scalar * If it’s ambiguous whether a field refers to an object/list vs. a scalar