strapi-common-api

provide a "strapi client SDK" wrapped some common request api service functions and strapi types support for strapi based frontend apps, and provide some key typescript types hint help, which is something that is not yet officially implemented by strapi[1] [2]

data types were generated by types-4-strapi, but some types need some manual correction, like "createdAt", "updatedAt", etc..

see also strapi, typescript

install

npm install strapi-common-api axios qs -s 

or

yarn add strapi-common-api axios qs

usage - strapi-client

you can create your customized strapi client like this, the key types were wrapped in functions below, declare the type of the entity generated by types-4-strapi to get the correct type prompt information

1import {createStrapiClient} from "strapi-common-api";
2import {Post} from "./Post";
3
4const {
5    strapiClient,
6    collection,
7    single,
8    auth
9} = createStrapiClient("http://localhost:1337/api", {/* some axios config */})
10
11// customize your client
12strapiClient.interceptors.request.use(config => config)
13
14collection.getMany<Post>('posts', {
15    populate: ["comments"],
16    fields: ["user", "content"]
17})

usage - functions

besides strapi client, you can also use these function directly like this.

but at first remember to override strapi request instance, which based on axios module, you can customize your interceptors (such as add jwt token before request) or some other params (such as base url)

1import {auth, collection, single, strapiRequest} from "strapi-common-api"
2import {Post} from "./Post";
3import {Global} from "./Global";
4
5// override your strapi api url like this
6strapiRequest.defaults.baseURL = "http://localhost:1337/api"// defalut base url value
7
8// here your editor will give you some hints on params and return data
9auth.login({identifier, password})
10    .then(({user, jwt}) => {
11        // do something ...
12    })
13
14collection.getMany<Post>("posts", {
15    filters: {
16        title: {
17            $eq: "test"
18        }
19    },
20    populate: {// support multi-level populate
21        user: {
22            populate: ["avatar"]
23        }
24    }
25}).then(({data, meta}) => {
26    // do something ...
27})
28
29single.get<Global>("global").then(r => {
30    // do something ...
31})

collection type api

• getMany

get many resources

Params:

type – strapi content-type name

query – strapi query object

• getOne

get one resource

Params:

type – strapi content-type name

id – resources id

query – strapi query object

• post

add one resource

Params:

type – strapi content-type name

data – post data

query – strapi query object

• put

put one resource

Params:

type – strapi content-type name

id – resource id

data – post data

query – strapi query object

• remove

remove one resource

Params:

type – strapi content-type name

id – resource id

query – strapi query object

single type api

• get
• put
• remove

auth api

• login
• register
• forgotPassword
• resetPassword
• changePassword
• sendEmailConfirm
• emailConfirm

usage - types

your IDE will give some hints when coding objects of these types, like this

err... there are too many types exported, here only introduce some key types

Populate

strapi populate object type

1import {Populate} from "strapi-common-api";
2import {Post} from "./Post";
3
4type P = Populate<Post>
5
6// common populate
7const p1: P = "deep"
8const p2: P = ["deep", 10]
9const p3: P = 10
10const p4: P = "*"
11const p5: P = ["user", "comments"]
12const p6: P = {
13    // multi level populate
14    user: {
15        populate: "*"
16    },
17    comments: {
18        populate: ["user", "post", "comment_votes"]
19    },
20
21    // deep populate
22    post_likes: {
23        populate: {
24            user: {
25                populate: "*"
26            }
27        }
28    }
29}
30const p7: P = {
31    comments: "*",
32    post_votes: "*",
33    user: "*",
34    post_likes: {
35        populate: ["user"]
36    }
37}

Filters

strapi filters object type

1import {Filters} from "strapi-common-api";
2import {Post} from "./Post";
3
4type F = Filters<Post>
5
6const f1: F = {
7    // common field
8    content: {
9        $contains: "haha"
10    },
11
12    // relation field
13    user: {
14        username: {
15            $eq: "littlebadbad",
16            $null: true,
17            $containsi: "little",
18            $startsWith: "l"
19        }
20    },
21
22    // array relation field
23    comments: {
24        content: {
25            $startsWith: "haha"
26        },
27        user: {
28            username: {
29                $startsWith: "l"
30            }
31        }
32    },
33
34    // logical operator filter
35    $and: [
36        {content: {$contains: "hello"}},
37        {title: {$contains: "hi"}}
38    ],
39    $not: {
40        user: {
41            username: {
42                $startsWith: "a"
43            }
44        }
45    }
46}

Sort

strapi sort object type

1import {Sort} from "strapi-common-api";
2import {Post} from "./Post";
3
4type S = Sort<Post>
5
6const s1: S = "content"
7const s2: S = ["content", "id"]
8const s3: S = {
9    content: "DESC",
10    title: "ASC"
11}
12const s4: S = [
13    {
14        content: "DESC"
15    },
16    {
17        title: "ASC"
18    }
19]

Query

query object followed by each strapi url, use qs library to stringify it, schema of query object follows the strapi api parameters

includes: locale, filters, publicationState, pagination, sort, fields, populate

1// Post type was generated by types-4-strapi
2import {Post} from "./Post";
3import {Query, Payload} from "strapi-common-api"
4
5export function getPosts(query?: Query<Post>): Promise<Payload<Post[]>> {
6    return strapiRequest.get(`/posts?${qs.stringify(query, {encodeValuesOnly: true})}`)
7        .then(r => r.data)
8}
9
10// here your editor will give you some type hints
11getPosts({
12    filters: {
13        title: {$contains: "test"}
14    },
15    populate: ["user"],
16    sort: ["updatedAt"]
17})