{"id":23468277,"url":"https://github.com/traverson/traverson-angular","last_synced_at":"2025-04-14T14:05:58.609Z","repository":{"id":22517335,"uuid":"25857734","full_name":"traverson/traverson-angular","owner":"traverson","description":"Seamless  AngularJS integration for Traverson","archived":false,"fork":false,"pushed_at":"2022-12-08T07:42:44.000Z","size":2790,"stargazers_count":16,"open_issues_count":18,"forks_count":5,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-12-08T18:33:21.804Z","etag":null,"topics":["angular","angularjs","hypermedia","hypermedia-client","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"prettier/prettier-eslint","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/traverson.png","metadata":{"files":{"readme":"readme.markdown","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-28T07:26:21.000Z","updated_at":"2020-05-04T20:48:17.000Z","dependencies_parsed_at":"2022-08-05T18:15:13.557Z","dependency_job_id":null,"html_url":"https://github.com/traverson/traverson-angular","commit_stats":null,"previous_names":["basti1302/traverson-angular"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traverson%2Ftraverson-angular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traverson%2Ftraverson-angular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traverson%2Ftraverson-angular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traverson%2Ftraverson-angular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/traverson","download_url":"https://codeload.github.com/traverson/traverson-angular/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231104392,"owners_count":18328379,"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":["angular","angularjs","hypermedia","hypermedia-client","javascript"],"created_at":"2024-12-24T13:50:34.877Z","updated_at":"2024-12-24T13:50:35.550Z","avatar_url":"https://github.com/traverson.png","language":"JavaScript","readme":"traverson-angular\n=================\n\nAngularJS integration for Traverson, the JS Hypermedia Client\n-------------------------------------------------------------\n\n[![Build Status](https://travis-ci.org/traverson/traverson-angular.png?branch=master)](https://travis-ci.org/traverson/traverson-angular)\n[![Dependency Status](https://david-dm.org/traverson/traverson-angular.png)](https://david-dm.org/traverson/traverson-angular)\n[![NPM](https://nodei.co/npm/traverson-angular.png?downloads=true\u0026stars=true)](https://nodei.co/npm/traverson-angular/)\n[![Greenkeeper badge](https://badges.greenkeeper.io/traverson/traverson-angular.svg)](https://greenkeeper.io/)\n\n| File Size (browser build) | KB |\n|---------------------------|---:|\n| minified \u0026 gzipped        | 19 |\n| minified                  | 66 |\n\nIntroduction\n------------\n\ntraverson-angular offers seamless integration of [Traverson](https://github.com/traverson/traverson) with AngularJS. Traverson comes in handy when consuming REST APIs that follow the HATEOAS principle, that is, REST APIs that have links between their resources. If you don't know Traverson, you should probably have a look at its [GitHub page](https://github.com/traverson/traverson) or at this [introductory blog post](https://blog.codecentric.de/en/2013/11/traverson/) first.\n\ntraverson-angular wraps Traverson in an AngularJS module and converts the original callback based API into an API based on promises.\n\nInstallation\n------------\n\n### npm\n\nSee [below](#using-npm-and-browserify).\n\n### Download\n\nYou can grab a download from the [latest release](https://github.com/traverson/traverson-angular/releases/latest). All downloads include traverson-angular and a bundled Traverson library, so you do not need to include Traverson separately. Here are your options:\n\n* `traverson-angular.min.js`: Minified build with UMD. This build can be used with a script tag or with an AMD loader like RequireJS (untested). It will register the AngularJS module `traverson`, which you can use as a dependency of your module (see below). **If in doubt, use this build.**\n* `traverson-angular.js`: Non-minified build with UMD. Same as above, just larger.\n* `traverson.external.min.js`: Minified require/external build. Created with browserify's `--require` parameter and intended to be used (required) from other browserified modules, which were created with `--external traverson-angular`. This build could be used if you use browserify but do not want to bundle traverson-angular and Traverson with your own browserify build but keep it as a separate file.\n* `traverson.external.js`: Non-minified require/external build, same as before, just larger.\n\n### Bower\n\n`bower install traverson-angular --save`\n\nUsage\n-----\n\n```javascript\nangular.module('my-app', ['traverson']);\n```\n\n```javascript\nangular.module('my-app').service('apiService', function(traverson) {\n  ...\n});\n```\n\nHave a look at the examples in the repository:\n\n* [Example 1](https://github.com/traverson/traverson-angular/blob/master/browser/example/index.html) ([JavaScript here](https://github.com/traverson/traverson-angular/blob/master/browser/example/traverson-angular-example.js))\n* [GitHub API example](https://github.com/traverson/traverson-angular/blob/master/browser/example/github.html) ([JavaScript here](https://github.com/traverson/traverson-angular/blob/master/browser/example/github-example.js))\n\nUsing npm and Browserify\n------------------------\n\nIf you are using npm and [Browserify](http://browserify.org/) and writing your [AngularJS app as CommonJS modules](https://blog.codecentric.de/en/2014/08/angularjs-browserify/), instead of downloading a release, you can install it with `npm install traverson-angular -S`.\n\nThis is how your code using traverson-angular would look like:\n```javascript\nvar angular = require('angular');\nvar traverson = require('traverson-angular');\nvar app = angular.module('my-app', [traverson.name]);\n\n...\n\napp.service('apiService', function(traverson) {\n  ...\n});\n\n```\n\nSee [here](https://github.com/traverson/traverson-angular/tree/master/browser/example/browserify) for a complete, working example of a CommonJS based AngularJS app using traverson-angular, build with Browserify.\n\nTo `require` angular-core like this, you need a shim in your package.json, like this:\n\n```javascript\n{\n  ...\n  \"dependencies\": {\n    \"angular\": \"^1.3.4\",\n    ...\n  },\n  \"browser\": {\n    \"angular\": \"./angular/angular-common-js.js\"\n  }\n}\n\n```\n\n`angular-common-js.js:`\n```javascript\nrequire('./angular.js');\nmodule.exports = angular;\n```\n\nBrowserify your app as usual - Browserify will include traverson-angular, Traverson itself and its dependencies for you.\n\nAPI\n---\n\nYou should refer to [Traverson's docs](https://github.com/traverson/traverson/blob/master/readme.markdown) for general info how to work with Traverson. Anything that works with Taverson also works with traverson-angular. The only difference is that traverson-angular's methods are not callback-based but work with promises.\n\nSo this code, which uses Traverson directly:\n\u003cpre lang=\"javascript\"\u003e\ntraverson\n.from('http://api.example.com')\n.newRequest()\n.follow('link_to', 'resource')\n\u003cb\u003e.getResource(function(error, document) {\n  if (error) {\n    console.error('No luck :-)')\n  } else {\n    console.log('We have followed the path and reached our destination.')\n    console.log(JSON.stringify(document))\n  }\n});\u003c/b\u003e\n\u003c/pre\u003e\nbecomes this with traverson-angular:\n\u003cpre lang=\"javascript\"\u003e\ntraverson\n.from('http://api.example.com')\n.newRequest()\n.follow('link_to', 'resource')\n\u003cb\u003e.getResource()\n.result\n.then(function(document) {\n  console.log('We have followed the path and reached our destination.')\n  console.log(JSON.stringify(document))\n}, function(err) {\n  console.error('No luck');\n});\u003c/b\u003e\n\u003c/pre\u003e\n\nThe only difference is `.getResource(function(error, document) {` =\u003e `.getResource().result.then(function(document) {`.\n\nActually, the object returned by `getResource` has three properties:\n* `result`: the promise representing the link traversal,\n* `continue`: a function that can be used to [continue](#continuing-a-link-traversal) a finished link traversal and\n* `abort`: a function that can be used to [abort](#aborting-the-link-traversal) link traversal that is in progress.\n\nThe following action methods of the Traverson request builder return such an object (`{ result, continue, abort }`) when used via traverson-angular:\n\n* `get()`\n* `getResource()`\n* `getUri()`\n* `post(payload)`\n* `put(payload)`\n* `patch(payload)`\n* `delete`\n\n### How HTTP Status Code Are Handled\n\nIn contrast to AngularJS' `$http` service, Traverson and traverson-angular do not interpret status codes outside of the 2xx range as an error condition. Only network problems (host not reachable, timeouts, etc.) lead to a rejection of the promise, that is, only those trigger the error callback. Completed HTTP requests, even those with status 4xx or 5xx are interpreted as a success and trigger the success callback. This applies only to the last request in a traversal, HTTP requests *during* the traversal that respond with 4xx/5xx are interpreted as an error (because the traversal can not continue).\n\nThis also holds when using `.useAngularHttp()` (see below).\n\n### Using AngularJS' $http Service Instead Of Traverson's HTTP Module\n\nTraverson has it's own HTTP module (based on [superagent](https://github.com/visionmedia/superagent)) and by default, this is used to make HTTP requests. If you want to use Traverson in a project that makes use of AngularJS' $http service and its configuration possibilities (default headers, interceptors and so on), these configurations do not apply automatically to the requests issued by Traverson. If you want that, you can configure traverson-angular to use $http instead of Traverson's HTTP module by calling `useAngularHttp()` on the request builder.\n\nExample:\n\n\u003cpre lang=\"javascript\"\u003e\ntraverson\n.from('http://api.example.com')\n\u003cb\u003e.useAngularHttp()\u003c/b\u003e\n.newRequest()\n.follow('link_to', 'resource')\n.getResource()\n.result\n.then(function(document) {\n  ...\n});\n\u003c/pre\u003e\n\n### Continuing a Link Traversal\n\nSee [Traverson's README](https://github.com/traverson/traverson#continuing-a-link-traversal) for a general description of the `continue()` feature. This section just describes how to use it with traverson-angular.\n\nThe object returned by the action methods (`get`, `getResource`, `getUrl`, `post`, `put`, `patch`, `delete`) have a property `continue` which is a function that can be used to obtain a promise that is resolved when the link traversal finishes (as does the `result` promise) and which gives you a request builder instance that starts at the last URL/resource of the finished link traversal. It can be used just as the standard [request builder](https://github.com/traverson/traverson/blob/master/api.markdown#request-builder). That is, it has the same configuration and action methods. It enables you to continue the link traversal from the last target resource and follow more links from there.\n\nSo while with plain vanilla Traverson (not traverson-angular) you would continue a successful link traversal process like this:\n\n```javascript\ntraverson\n.from(rootUrl)\n.follow('link1', 'link2')\n.getResource(function(err, firstResource, traversal) {\n  if (err) { return done(err); }\n  // do something with the first resource, maybe decide where to go from here.\n  traversal\n  .continue()\n  .follow('link3', 'link3')\n  .getResource(function(err, secondResource) {\n    if (err) { return done(err); }\n    // do something with the second resource\n  });\n});\n```\n\n...this is how it is done with traverson-angular:\n\n\u003cpre lang=\"javascript\"\u003e\nvar request =\ntraverson\n.from('http://api.example.com')\n.follow('link1', 'link2');\n.getResource();\n\nrequest.result.then(successCallback, errorCallback);\n\nrequest.continue().then(function(request) {\n  request\n  .follow('link3', 'link4');\n  .getResource()\n  .result\n  .then(successCallback2, errorCallback2);\n});\n\u003c/pre\u003e\n\n### Aborting the Link Traversal\n\nAs mentioned above, the object returned by the action methods returns an object which also has an `abort()` function.\n\nSo while with plain vanilla Traverson (not traverson-angular) you would abort a link traversal process like this\n\n\u003cpre lang=\"javascript\"\u003e\nvar handle =\ntraverson\n.from('http://api.example.com')\n.newRequest()\n.follow('link_to', 'resource')\n.getResource(...);\n\n// abort the link traversal\n\u003cb\u003ehandle.abort();\u003c/b\u003e\n\u003c/pre\u003e\n\n...this is how it is done with traverson-angular:\n\n\u003cpre lang=\"javascript\"\u003e\nvar handle =\ntraverson\n.from('http://api.example.com')\n.newRequest()\n.follow('link_to', 'resource')\n.getResource();\n\n// register callbacks\nhandle.result.then(successCallback, errorCallback);\n\n// abort the link traversal\n\u003cb\u003ehandle.abort()\u003c/b\u003e\n\u003c/pre\u003e\n\ntraverson-angular With Media Type Plug-Ins\n------------------------------------------\n\nYou can use all media type plug-ins that are available for Traverson with traverson-angular. Here is how:\n\n* Make sure the JavaScript for the media type plug-in has been loaded (for example, add a script tag for traverson-hal.min.js).\n* Register the media type with a line like this: `traverson.registerMediaType(TraversonJsonHalAdapter.mediaType, TraversonJsonHalAdapter);`.\n* If necessary force Traverson to use the media type in question with `setMediaType(...)` (for HAL, you can use the convenience method `.jsonHal()` instead).\n* If necessary, add Accept headers so your server knows you want to receive a particular media type. Example: `.withRequestOptions({ headers: { 'accept': 'application/hal+json' } })`.\n\nHere is a snippet outlining how to use traverson-angular with [traverson-hal](https://github.com/traverson/traverson-hal):\n\n```html\n\u003cscript src=\"traverson-angular.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"traverson-hal.min.js\"\u003e\u003c/script\u003e\n```\n\n```javascript\ntraverson.registerMediaType(TraversonJsonHalAdapter.mediaType,\n                            TraversonJsonHalAdapter);\ntraverson\n.from(rootUri)\n.jsonHal()\n.withRequestOptions({ headers: { 'accept': 'application/hal+json' } })\n.follow(...)\n.getResource()\n.result\n.then(...);\n```\n\nYou can find a complete working example for integrating traverson-hal with traverson-anglar in [browser/example/hal.html](https://github.com/traverson/traverson-angular/blob/master/browser/example/hal.html) and [browser/example/hal.js](https://github.com/traverson/traverson-angular/blob/master/browser/example/hal.js).\n\n\nContributing\n------------\n\nSee [Contributing to traverson-angular](https://github.com/traverson/traverson-angular/blob/master/CONTRIBUTING.md).\n\n\nCode of Conduct\n---------------\n\nSee [Code of Conduct](https://github.com/traverson/traverson-angular/blob/master/CODE_OF_CONDUCT.md).\n\n\nRelease Notes\n-------------\n\nSee [CHANGELOG](https://github.com/traverson/traverson-angular/blob/master/CHANGELOG.md).\n\n\nLicense\n-------\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraverson%2Ftraverson-angular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftraverson%2Ftraverson-angular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraverson%2Ftraverson-angular/lists"}