Decorator-powered REST client for Angular and its HttpClient
npm install @elemental-concept/grappa17.0.0 | 13 up to 17 (included) | 18 |
16.0.0 | 13 up to 16 (included) | 16 |
1.1.1 | 13 up to 15 (included) | 14 |
npm i --save @elemental-concept/grappa
GrappaModule to your main AppModule to imports section.
typescript
@NgModule({
declarations: [ ... ],
imports: [
...,
GrappaModule
],
providers: [ ],
bootstrap: [ ... ]
})
export class AppModule {
}
`
📖 Introduction
Grappa minimises boilerplate code required for REST clients and streamlines request and response modifications with filters.
Simply define a list of methods which reflect REST API:
`typescript
@Injectable()
@RestClient('http://example.com/api/')
export class UserService {
@GET('/users')
list: () => Observable;
@GET('/users/{0}')
find: (id: number) => Observable;
@PATCH('/users/{0}')
update: (id: number, user: User) => Observable;
@POST('/users')
create: (user: User) => Observable;
@PUT('/users/{0}')
update: (id: number, user: User) => Observable;
}
`
Grappa will auto-generate required class methods which can be easily called from any component:
`typescript
@Component({
// ...
})
export class AppComponent {
constructor(private userService: UserService) {
userService.find(42).subscribe(user => console.log(user));
}
}
`
Define @BeforeRequest() filter methods to uniformly modify data being sent to the API.
A good example could be JWT injection, but we are covering that with a separate library
Grappa JWT
Custom header injection is a good example:
`typescript
@Injectable()
@RestClient('http://example.com/api/')
export class UserService {
// ...
constructor(private authService: AuthService) {
}
@BeforeRequest()
private customHeaders(request: RestRequest) {
request.headers = {
...request.headers,
'X-Xid': id,
'X-Client-Id': clientId,
'X-User-Id': userId,
};
}
}
`
Use @AfterRequest() to transform responses and inject global error handlers:
`typescript
@Injectable()
@RestClient('http://example.com/api/')
export class UserService {
// ...
@AfterRequest()
tranformResponse(response: Observable>) {
return response.map(item => User.fromResponse(item.body));
}
@AfterRequest()
handleErrors(response: Observable>) {
return response.catch(error => {
alert('Error!');
return Observable.of(error);
});
}
}
`
---
API
Decorators on a class and its properties define how a request will be handled.
$3
Optional decorator which allows to define base URL for all REST methods in a class. If decorator is not present
or baseUrl argument is empty string, null or undefined, then it is assumed that property decorators will contain
full URLs.
Example with @RestClient:
`typescript
@Injectable()
@RestClient('http://example.com/api/')
export class UserService {
@GET('/users')
list: () => Observable; // List method will call http://example.com/api/users
}
`
Example without @RestClient:
`typescript
@Injectable()
export class UserService {
@GET('http://somedomain.org/users')
list: () => Observable; // List method will call http://somedomain.org/users
}
`
---
$3
Makes HTTP GET request to the specified end-point. Arguments passed to the decorated function can be inserted into
end-point URL using index based templates. Indices start at 0. Example:
`typescript
@GET('/users/{0}/posts?page={1}')
getUserPosts: (userId: number, page: number) => Observable;
`
{0} will be replaced with userId value and {1} will be replaced with page value.
---
$3
Makes HTTP PATCH request to the specified end-point. Arguments passed to the decorated function can be inserted into
end-point URL using index based templates. Indices start at 0. Last function argument will be used as a PATCH body.
`typescript
@PATCH('/users/{0}', options: RequestOptions = {})
update: (userId: number, user: User) => Observable;
`
---
$3
Makes HTTP POST request to the specified end-point. Arguments passed to the decorated function can be inserted into
end-point URL using index based templates. Indices start at 0. Last function argument will be used as a POST body.
`typescript
@POST('/users')
create: (user: User) => Observable;
`
---
$3
Makes HTTP PUT request to the specified end-point. Arguments passed to the decorated function can be inserted into
end-point URL using index based templates. Indices start at 0. Last function argument will be used as a PUT body.
`typescript
@PUT('/users/{0}', options: RequestOptions = {})
update: (userId: number.user: User) => Observable;
`
---
$3
Makes HTTP DELETE request to the specified end-point. Arguments passed to the decorated function can be inserted into
end-point URL using index based templates. Indices start at 0. Example:
`typescript
@DELETE('/users/{0}')
remove: (userId: number) => Observable;
`
---
$3
Runs decorated method before every request in a class.
`typescript
@BeforeRequest()
beforeFilter(request: RestRequest) {
request.headers[ 'X-Dummy' ] = 'Abcde';
}
`
---
$3
Runs decorated method after every request in a class.
`typescript
@AfterRequest()
afterFilter(response: Observable>) {
return response.map(r => r.body.value);
}
`
---
$3
Configuration for specific GET, POST, PATCH, PUT and DELETE requests.
`typescript
export interface RequestOptions {
observe?: ObserveOptions;
query?: number | boolean;
emptyBody?: boolean;
}
export enum ObserveOptions {
Body = 'body',
Response = 'response'
}
`
Given
`typescript
@GET('/users/{0}/posts?page={1}')
getUserPosts: (userId: number, page: number) => Observable;
`
you'll have {1} as the page attribute, but if instead you have multiple query params, the best approach is to have a
single object and then use the query option:
`typescript
@GET('/users/{0}/posts', { query: true })
getUserPosts: (userId: number, { page: number, search: string, sort: string, hideOutOfStock: boolean }) => Observable;
`
This way Grappa will translate the object into a list of query params, like this:
`typescript
/users/{0}/posts?page=${ page }&search=${ search }&sort=${ sort }&hideOutOfStock=${ hideOutOfStock }
`
If for any reason you need to send a PUT or a POST without a body (which is not a good practise), we added a new
flag emptyBody, that allow that. So you could send something like this:
`typescript
@PUT('/users/{0}', { emptyBody: true })
getUserPosts: (userId) => Observable;
`
If for any reason you need to send a PUT or a POST url params as well as query params as well body object,
you need to specify which arg index is the query params
`typescript
@PUT('/users/{0}', { query: 1 })
getUserPosts: (userId, queryParams: { name: string }, body: User) => Observable;
`
---
$3
Allows to specify the names of request methods specific filter should apply.
`typescript
export type OptionalList = T | T[] | null;
`
Usage:
`typescript
@GET('/users')
get: () => Observable;
@POST('/users')
create: (user: User) => Observable;
@BeforeRequest('create')
beforeFilter(request: RestRequest) {
// This filter function will only apply to create() calls
}
``