README
Architect SDK
Overview
We developed JavaScript/Typescript SDK library in order to make it easier to use Architect services. The library should spare your time and effort, so you can focus on building great apps and beautiful UIs. You can read bellow how easy it is to use.
Getting started
Installation
Using npm
npm install architect-sdk
Or using yarn
yarn add architect-sdk
Usage
JavaScript
import client from './architect-sdk';
const architect = client({
baseUrl: 'https://example.essentialz.cloud', // Your project url
});
Typescript
If you use typescript, you would probably like to define your schema of resources. This will give you full autocomplete support in your IDE for all resources you define.
import client, { ArchitectResource } from 'architect-sdk';
type ArchitectSchema = {
cats: ArchitectResource,
dogs: ArchitectResource,
birds: ArchitectResource,
}
const architect = client<ArchitectSchema>({
baseUrl: 'https://example.essentialz.cloud', // Your project url
});
Options
When you create architect instance using architect(config: ArchitectConfig): ArchitectSDK
function you should provide the following configurations:
Parameter | Required/Optional | Type | Default | Description |
---|---|---|---|---|
baseUrl |
required | string |
Absolute url to your project domain | |
recommendedCase |
optional | boolean |
true |
Defines whether the SDK will convert names of properties from camelCase to snake_case before sending and after receiving them. |
API reference
Authentication
Depending on which auth provider you want to use for authentication of users,
you should provide necessary credentials, and call login
function with them.
const credentials =
// Email
{
email: 'user@example.com',
password: 'strongPassWord'
}
// Apple
{
identityToken: 'validAppleIdentityToken'
}
// Facebook
{
accessToken: 'validFacebookIdentityToken'
}
// Google
{
idToken: 'validGoogleIdToken'
};
const provider = 'email' | 'apple' | 'facebook' | 'google';
architect.login(credentials, provider)
.then((response) => {
// Handle successful response
})
.catch((error) => {
// Display error messages in your UI
});
After successful login, all API requests you make using SDK will contain authorization headers related to a specific user.
Invalidating current auth session can be done by calling logout
method.
architect.logout();
Also, you can always check if the user is authenticated.
architect.isAuthenticated(); // true or false
Managing resources
There is no limit how a resource can be named as long the name isn't one of reserved words.
You can call it whatever you like and architect SDK will provide you methods for CRUD actions on it.
We recommend using plural nouns for resource names.
To access these you should simply call architect.<resource-name>
and it will return you a service with the following methods:
Fetching all resources:
getAll(): Promise<ArchitectResource[]>
Fetching a single resource:
get(resourceId: string): Promise<ArchitectResource>
Creating a resource:
create(resourceData: Record<String, any>): Promise<ArchitectResource>
Updating a resource:
update(resourceId: string, resourceData: Record<String, any>): Promise<ArchitectResource>
Deleting a resource:
delete(resourceId: string): Promise<boolean>
Currently, ArchitectResource
is equivalent to Record<string, any>
but in the future it will contain many useful utilities.
Example usage
Here is the example how you can manage books resource using SDK.
// This will return all books
const allBooks = await architect.books.getAll();
// This will return single book with id = '5';
const specialBook = await architect.books.get('5');
// Create a new book
const newBook = architect.books.create({
name: 'The Adventures of Tom Sawyer',
author: 'Mark Twain',
});
// Update book with id = '5'
const updatedBook = await architect.books.update('5', {
numberOfPages: 366
});
// Delete book with id = '5'
await architect.books.delete('5');
Reserved names
The following words cannot be used as resource name.
login
,logout
&isAuthenticated
- reserved for auth methods.files
- reserved for the service which is used for managing files.
Managing files
Architect SDK comes with files
service for managing files. It contains the following methods:
Single file upload
upload(file: File): Promise<ArchitectFileResource>
Bulk upload
uploadBulk(files: File[]): Promise<ArchitectFileResource[]>
Currently, ArchitectFileResource
is equivalent to { url: string }
.
Example usage
architect.files.upload(file)
.then((file) => {
// Manage uploaded file
// { url: ''}
})
.catch((error) => {
// Handle upload error
});
architect.files.uploadBulk(files)
.then((files) => {
// Manage uploaded files
// [{ url: ''}, { url: ''}, ...]
})
.catch((error) => {
// Handle upload error
});