Home

Awesome

Angular in-memory-web-api

Build Status

An in-memory web api for Angular demos and tests that emulates CRUD operations over a RESTy API.

It intercepts Angular Http and HttpClient requests that would otherwise go to the remote server and redirects them to an in-memory data store that you control.

See Austin McDaniel's article for a quick introduction.

It used to work and now it doesn't :-(

Perhaps you installed a new version of this library? Check the CHANGELOG.md for breaking changes that may have affected your app.

If that doesn't explain it, create an issue on github, preferably with a small repro.

Use cases

LIMITATIONS

The in-memory-web-api exists primarily to support the Angular documentation. It is not supposed to emulate every possible real world web API and is not intended for production use.

Most importantly, it is always experimental. We will make breaking changes and we won't feel bad about it because this is a development tool, not a production product. We do try to tell you about such changes in the CHANGELOG.md and we fix bugs as fast as we can.

HTTP request handling

This in-memory web api service processes an HTTP request and returns an Observable of HTTP Response object in the manner of a RESTy web api. It natively handles URI patterns in the form :base/:collectionName/:id?

Examples:

  // for requests to an `api` base URL that gets heroes from a 'heroes' collection 
  GET api/heroes          // all heroes
  GET api/heroes/42       // the hero with id=42
  GET api/heroes?name=^j  // 'j' is a regex; returns heroes whose name starting with 'j' or 'J'
  GET api/heroes.json/42  // ignores the ".json"

The in-memory web api service processes these requests against a "database" - a set of named collections - that you define during setup.

Basic setup

<a id="createDb"></a>

Create an InMemoryDataService class that implements InMemoryDbService.

At minimum it must implement createDb which creates a "database" hash whose keys are collection names and whose values are arrays of collection objects to return or update. For example:

import { InMemoryDbService } from 'angular-in-memory-web-api';

export class InMemHeroService implements InMemoryDbService {
  createDb() {
    let heroes = [
      { id: 1, name: 'Windstorm' },
      { id: 2, name: 'Bombasto' },
      { id: 3, name: 'Magneta' },
      { id: 4, name: 'Tornado' }
    ];
    return {heroes};
  }
}

Notes

Import the in-memory web api module

Register your data store service implementation with the HttpClientInMemoryWebApiModule in your root AppModule.imports calling the forRoot static method with this service class and an optional configuration object:

import { HttpClientModule } from '@angular/common/http';
import { HttpClientInMemoryWebApiModule } from 'angular-in-memory-web-api';

import { InMemHeroService } from '../app/hero.service';

@NgModule({
 imports: [
   HttpClientModule,
   HttpClientInMemoryWebApiModule.forRoot(InMemHeroService),
   ...
 ],
 ...
})
export class AppModule { ... }

Notes

Examples

The tests (src/app/*.spec.ts files) in the github repository are a good place to learn how to setup and use this in-memory web api library.

See also the example source code in the official Angular.io documentation such as the HttpClient guide and the Tour of Heroes.

Advanced Features

Some features are not readily apparent in the basic usage described above.

Configuration arguments

The InMemoryBackendConfigArgs defines a set of options. Add them as the second forRoot argument:

  InMemoryWebApiModule.forRoot(InMemHeroService, { delay: 500 }),

Read the InMemoryBackendConfigArgs interface to learn about these options.

Request evaluation order

This service can evaluate requests in multiple ways depending upon the configuration. Here's how it reasons:

  1. If it looks like a command, process as a command
  2. If the HTTP method is overridden, try the override.
  3. If the resource name (after the api base path) matches one of the configured collections, process that
  4. If not but the Config.passThruUnknownUrl flag is true, try to pass the request along to a real XHR.
  5. Return a 404.

See the handleRequest method implementation for details.

Default delayed response

By default this service adds a 500ms delay to all data requests to simulate round-trip latency.

Command requests have zero added delay as they concern in-memory service configuration and do not emulate real data requests.

You can change or eliminate the latency by setting a different delay value:

  InMemoryWebApiModule.forRoot(InMemHeroService, { delay: 0 }),    // no delay
  InMemoryWebApiModule.forRoot(InMemHeroService, { delay: 1500 }), // 1.5 second delay

Simple query strings

Pass custom filters as a regex pattern via query string. The query string defines which property and value to match.

Format: /app/heroes/?propertyName=regexPattern

The following example matches all names start with the letter 'j' or 'J' in the heroes collection.

/app/heroes/?name=^j

Search pattern matches are case insensitive by default. Set config.caseSensitiveSearch = true if needed.

<a id="passthru"></a>

Pass thru to a live server

If an existing, running remote server should handle requests for collections that are not in the in-memory database, set Config.passThruUnknownUrl: true. Then this service will forward unrecognized requests to the remote server via the Angular default XHR backend (it depends on whether your using Http or HttpClient).

<a id="commands"></a>

Commands

The client may issue a command request to get configuration state from the in-memory web api service, reconfigure it, or reset the in-memory database.

When the last segment of the api base path is "commands", the collectionName is treated as the command.

Example URLs:

  commands/resetdb   // Reset the "database" to its original state
  commands/config    // Get or update this service's config object

Usage:

  http.post('commands/resetdb', undefined);
  http.get('commands/config');
  http.post('commands/config', '{"delay":1000}');

Command requests do not simulate real remote data access. They ignore the latency delay and respond as quickly as possible.

The resetDb command calls your InMemoryDbService data service's createDb method with the RequestInfo object, enabling the createDb logic to adjust its behavior per the client request.

In the following example, the client includes a reset option in the command request body:

http
  // Reset the database collections with the `clear` option
  .post('commands/resetDb', { clear: true }))

  // when command finishes, get heroes
  .concatMap(
    ()=> http.get<Data>('api/heroes')
        .map(data => data.data as Hero[])
  )

  // execute the request sequence and 
  // do something with the heroes
  .subscribe(...)

See the tests for other examples.

parseRequestUrl

The parseRequestUrl parses the request URL into a ParsedRequestUrl object. ParsedRequestUrl is a public interface whose properties guide the in-memory web api as it processes the request.

Default parseRequestUrl

Default parsing depends upon certain values of config: apiBase, host, and urlRoot. Read the source code for the complete story.

Configuring the apiBase yields the most interesting changes to parseRequestUrl behavior:

The actual api base segment values are ignored. Only the number of segments matters. The following api base strings are considered identical: 'a/b' ~ 'some/api/' ~ `two/segments'

This means that URLs that work with the in-memory web api may be rejected by the real server.

Custom parseRequestUrl

You can override the default parser by implementing a parseRequestUrl method in your InMemoryDbService.

The service calls your method with two arguments.

  1. url - the request URL string
  2. requestInfoUtils - utility methods in a RequestInfoUtilities object, including the default parser. Note that some values have not yet been set as they depend on the outcome of parsing.

Your method must either return a ParsedRequestUrl object or null|undefined, in which case the service uses the default parser. In this way you can intercept and parse some URLs and leave the others to the default parser.

Custom genId

Collection items are presumed to have a primary key property called id.

You can specify the id while adding a new item. The service will blindly use that id; it does not check for uniqueness.

If you do not specify the id, the service generates one via the genId method.

You can override the default id generator with a method called genId in your InMemoryDbService. Your method receives the new item's collection and collection name. It should return the generated id. If your generator returns null|undefined, the service uses the default generator.

responseInterceptor

You can change the response returned by the service's default HTTP methods. A typical reason to intercept is to add a header that your application is expecting.

To intercept responses, add a responseInterceptor method to your InMemoryDbService class. The service calls your interceptor like this:

responseOptions = this.responseInterceptor(responseOptions, requestInfo);

<a id="method-override"></a>

HTTP method interceptors

You may have HTTP requests that the in-memory web api can't handle properly.

You can override any HTTP method by implementing a method of that name in your InMemoryDbService.

Your method's name must be the same as the HTTP method name but all lowercase. The in-memory web api calls it with a RequestInfo object that contains request data and utility methods.

For example, if you implemented a get method, the web api would be called like this: yourInMemDbService["get"](requestInfo).

Your custom HTTP method must return either:

The RequestInfo is an interface defined in src/in-mem/interfaces.ts. Its members include:

req: Request;           // the request object from the client
collectionName: string; // calculated from the request url
collection: any[];      // the corresponding collection (if found)
id: any;                // the item `id` (if specified)
url: string;            // the url in the request
utils: RequestInfoUtilities; // helper functions

The functions in utils can help you analyze the request and compose a response.

In-memory Web Api Examples

The github repository demonstrates library usage with tested examples.

The HeroInMemDataService class (in src/app/hero-in-mem-data.service.ts) is a Hero-oriented InMemoryDbService such as you might see in an HTTP sample in the Angular documentation.

The HeroInMemDataOverrideService class (in src/app/hero-in-mem-data-override.service.ts) demonstrates a few ways to override methods of the base HeroInMemDataService.

The tests (see below) exercise these examples.

Build Instructions

Follow these steps for updating the library.

Testing

The "app" for this repo is not a real app. It's an Angular data service (HeroService) and a bunch of tests.

Note that the tsconfig.json produces a commonjs module. That's what Angular specs require. But when building for an app, it should be a es2015 module, as is the tsconfig-ngc.json for AOT-ready version of this library.

These tests are a work-in-progress, as tests often are.

The src/ folder is divided into

A real app would reference the in-memory web api node module; these tests reference the library source files.

The karma-test-shim.js adds the in-mem folder to the list of folders that SystemJS should resolve.

Rollup

The gulp "umd" task runs rollup for tree-shaking.

I don't remember if it ever worked without a lot of warnings. The v0.4.x release updated to rollup@0.49 which required updates to the rollup.config.js.

Still weirdly runs cjs rollup config first that I can’t find (which produces numerous warnings) before doing the right thing and running the umd config.

Also does not work if you follow instructions and use the output property of rollup.config.js; does work when configure it “wrong” and put the options in the root.

Ignoring these issues for now.