# Services
Services are classes that gets delegated some responsibility by upfront. With services, it's easy to adjust upfront's behaviour without having to extend the model and write elaborate overrides. You may switch them out or extend them to fit your needs. To see how you change the implementations, visit the global config page.
# Service Interfaces
Services have some interfaces that they need to implement on order to work.
# ApiCaller
ApiCaller an object with a call
method defined which is utilized by all the ajax requests initiated by upfront, and it is responsible for sending a request with the given data returning a Promise<ApiResponse>
. The arguments the call
method takes in order are:
url
- a stringmethod
- a string representing the http methoddata
(optional) - an object or FormData (opens new window)customHeaders
(optional) - an object with string keys and string or array of strings valuequeryParameters
(optional) - an object to send as query parameters in the url
# HandlesApiResponse
HandlesApiResponse's task is to handle the parsing of the ApiResponse returned by ApiCaller and deal with any errors. It defines a handle
method which takes a Promise<ApiResponse>
and it should return a Promise<any>
.
# ApiResponse
As you might have noticed in the above service interfaces they work with an object called ApiResponse
as opposed to a Response (opens new window). This is because this interface is more generic and can easily be implemented if deciding to use something other than the fetch (opens new window) api. The only keys always available on the object are the following properties:
TIP
Typescript users may use module augmentation (opens new window) to specify what their ApiResponse
is actually look like:
// shims/upfront.d.ts
import type { ApiResponse as BaseApiResponse } from '@upfrontjs/framework';
declare module '@upfrontjs/framework' {
interface ApiResponse extends BaseApiResponse {
myKey?: string;
}
}
2
3
4
5
6
7
8
Upfront provides the implementations for the above interfaces which should cover most use cases. If you don't set your own implementation, upfront will fall back to these default services.
- API - implements
ApiCaller
- ApiResponseHandler - implements
HandlesApiResponse
# Using Custom Services
# Implementing interfaces
If you're thinking about creating your own service, for reference you may check out the interfaces and/or the default implementation's source code.
Creating a service is easy as:
# Extending Services
If you just want to extend a service to add some functionality like adding initRequest() to the API, that can be achieved like so:
You can find examples of testing custom services in the Testing section.