{"id":13760281,"url":"https://github.com/lincolnloop/amygdala","last_synced_at":"2025-10-22T14:37:26.419Z","repository":{"id":14938469,"uuid":"17662996","full_name":"lincolnloop/amygdala","owner":"lincolnloop","description":"RESTful HTTP client for JavaScript powered web applications","archived":true,"fork":false,"pushed_at":"2017-05-13T03:19:04.000Z","size":830,"stargazers_count":393,"open_issues_count":7,"forks_count":22,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-09-26T04:08:26.832Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lincolnloop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-12T10:21:02.000Z","updated_at":"2024-07-03T15:40:23.000Z","dependencies_parsed_at":"2022-08-30T16:11:07.488Z","dependency_job_id":null,"html_url":"https://github.com/lincolnloop/amygdala","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincolnloop%2Famygdala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincolnloop%2Famygdala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincolnloop%2Famygdala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lincolnloop%2Famygdala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lincolnloop","download_url":"https://codeload.github.com/lincolnloop/amygdala/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224949760,"owners_count":17397230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T13:01:06.728Z","updated_at":"2025-10-22T14:37:26.025Z","avatar_url":"https://github.com/lincolnloop.png","language":"JavaScript","readme":"![Amygdala logo](https://raw.githubusercontent.com/lincolnloop/amygdala/master/static/logo.png)\n\nAmygdala is a RESTful HTTP library for JavaScript powered web applications. Simply configure it once with your API schema, and easily do GET, POST, PUT and DELETE requests with minimal effort and a consistent API.\n\nExamples:\n\n```javascript\n// GET\nstore.get('users').done(function() { ... });\n\n// POST\nstore.add('teams', {'name': 'Lincoln Loop', 'active': true}).done(function() { ... });\n```\n\n[![browser support](https://ci.testling.com/lincolnloop/amygdala.png)\n](https://ci.testling.com/lincolnloop/amygdala)\n\n## How it works\n\n### 1. INSTALL\n\n\n#### NPM/Browserify\n\n`npm install amygdala`.\n\n\n#### Bower\n\n`bower install amygdala`\n\n\n#### Browser\n\nDownload the latest [amygdala.js](https://github.com/lincolnloop/amygdala/blob/master/amygdala.js) file. Minified/build version coming soon.\n\n##### Dependencies:\n\n* [lodash](https://lodash.com): ^3.10.1\n* [q](https://github.com/kriskowal/q): ^1.0.1\n* [Wolfy87/EventEmitter](https://github.com/Wolfy87/EventEmitter): ^4.2.6\n\n\n### 2. SETUP\n\nTo create a new store, define the few possible settings listed below and your API schema.\n\n```javascript\nvar store = new Amygdala({\n  'config': {\n    'apiUrl': 'http://localhost:8000',\n    'idAttribute': 'url',\n    'headers': {\n      'X-CSRFToken': getCookie('csrftoken')\n    },\n    'localStorage': true\n  },\n  'schema': {\n    'users': {\n      'url': '/api/v2/user/'\n    },\n    'teams': {\n      'url': '/api/v2/team/',\n      'orderBy': 'name',\n      'oneToMany': {\n        'members': 'members'\n      },\n      parse: function(data) {\n        return data.results ? data.results : data;\n      },\n    },\n    'members': {\n      'foreignKey': {\n        'user': 'users'\n      }\n    }\n  }\n});\n```\n\n#### Configuration options:\n\n  * apiUrl - Full path to your base API url (required).\n  * idAttribute - global primary key attribute (required). \n  * headers - Any headers that you need to pass on each API request.\n  * localStorage - enable/disable the persistent localStorage cache.\n\n#### Schema options:\n  \n  * url - relative path for each \"table\" (required)\n  * orderBy - order by which you want to retrieve local cached data. eg (name, -name (for reverse))\n  * parse - Accepts a parse method for cases when your API also returns extra meta data.\n  * idAttribute - overrides key attribute (if different in this schema)\n\n\n#### Schema relations:\n\nWhen you want to include related data under a single request, for example, to minimize HTTP requests, having schema relations allows you to still have a clean separation when interacting with the data locally.\n\nConsider the following schema, that defines discussions that have messages, and messages that have votes:\n\n```javascript\nvar store = new Amygdala({\n    'config': {\n      'apiUrl': 'http://localhost:8000',\n      'idAttribute': 'url'\n    },\n    'schema': {\n      'discussions': {\n        'url': '/api/v2/discussion/',\n        'oneToMany': {\n          'children': 'messages'\n        }\n      },\n      'messages': {\n        'url': '/api/v2/message/',\n        'oneToMany': {\n          'votes': 'votes'\n        },\n        'foreignKey': {\n          'discussion': 'discussions'\n        }\n      },\n      'votes': {\n        'url': '/api/v2/vote/'\n      }\n    }\n  }\n);\n```\n\nIn this scenario, doing a query on a discussion will retrieve all messages and votes for that discussion:\n\n```javascript\nstore.get('discussions', {'url': '/api/v2/discussion/85273/'}).then(function(){ ... });\n```\n\nSince we defined relations on our schema, the message and vote data won't be stored on the discussion \"table\", but on it's own \"table\" instead.\n\n##### OneToMany:\n\n```javascript\n'oneToMany': {\n  'children': 'messages'\n}\n```\n\n`OneToMany` relations are the most common, and should be used when you have related data in form of an array. In this case, `children` is the attribute name on the response, and `messages` is the destination \"table\" for the array data.\n\n\n##### foreignKey:\n\n```javascript\n'foreignKey': {\n  'discussion': 'discussions'\n}\n```\n\n`foreignKey` relations are basically for one to one relations. In this case Amygdala will look for an object as value of `discussion` and move it over to the `discussions` \"table\" if one is found.\n\n\n### 3. USAGE\n\n#### Querying the remote API server:\n\nThe methods below, allow you to make remote calls to your API server.\n\n```javascript\n// GET\nstore.get('users').done(function() { ... });\n\n// POST\nstore.add('teams', {'name': 'Lincoln Loop', 'active': true}).done(function() { ... });\n\n// PUT\nstore.update('users', {'url': '/api/v2/user/32/', 'username': 'amy82', 'active': true}).done(function() { ... });\n\n// DELETE\nstore.remove('users', {'url': '/api/v2/user/32/'}).done(function() { ... });\n```\n\n\n#### In memory storage API:\n\nOn top of this, Amygdala also stores a copy of your data locally, which you can access through a couple different methods:\n\n\n###### Find and filtering:\n\n```javascript\n// Get the list of active users from memory\nvar users = store.findAll('users', {'active': true});\n\n// Get a single user from memory\nvar user = store.find('users', {'username': 'amy82'});\n\n// Get a single user by id for memory\nvar user = store.find('users', 1103747470);\n```\n\nIf you enable `localStorage`, the data is kept persistently. Because of this, once you instantiate Amygdala, your cached data will be loaded, and you can use it right away without having to wait for the remote calls. (We do not recommend using `localStorage` for production yet)\n\n\n##### Fetching related data:\n\nBy defining your schema and creating relations between data, you are then able to query your data objects for the related objects.\n\nIn the example schema above, discussions have a oneToMany relation with messages, and messages have a foreignKey relation back to discussions. This is how it you can use them.\n\n```javascript\n// Fetching related messages for a discussion (oneToMay)\nvar messages = store.find('discussions', '/api/v2/discussion/85273/').getRelated('messages');\n\n// Getting the discussion object from a message (foreignKey)\nvar discussion = store.find('message', '/api/v2/message/81273/').getRelated('discussion');\n```\n\nNote that Amygdala doesn't fetch data automagically for you here, so it's up you to fetch it before running the query.\n\n## Events\n\nAmygdala uses [Wolfy87/EventEmitter](https://github.com/Wolfy87/EventEmitter) under the hood\nto trigger some very basic events. Right now it only triggers two different events:\n\n* change\n* change:type\n\nTo listen to these events, you can use any of [Event Emitter's](https://github.com/Wolfy87/EventEmitter/blob/master/docs/guide.md#using-eventemitterr) binding methods or the [aliases](https://github.com/Wolfy87/EventEmitter/blob/master/docs/guide.md#method-aliases), the most common one being `on`:\n\n```javascript\n// Listen to any change in the store\nstore.on('change', function() { ... });\n\n// Listen to any change of a specific type\nstore.on('change:users', function() { ... });\n```\n","funding_links":[],"categories":["API","API [🔝](#readme)"],"sub_categories":["Runner","运行器","运行器e2e测试"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flincolnloop%2Famygdala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flincolnloop%2Famygdala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flincolnloop%2Famygdala/lists"}