Fetch WordPress API

This module provides a set of utility functions for interacting with a headless WordPress CMS via the WordPress REST API. It includes functions for fetching posts, pages, and categories, with support for custom fields and query parameters.

Installation

To install the package, run the following command:

npm install fetch-wordpress-api

Usage

Before using the package's functions, you need to configure the BASE_URL variable by calling the configure function and passing an object with the BASE_URL property set to the base URL of your WordPress site.

Here's an example of how to configure the BASE_URL and use the package's functions:

1import { configure, fetchPosts, PostFields } from 'fetch-wordpress-api';
2
3configure({ BASE_URL: 'https://example.com' });
4
5// This will return an array of posts objects
6const posts = await fetchPosts();
7
8// Fetch only 5 posts
9const posts = await fetchPosts(5);
10
11// Fetch 3 posts containing only the title, content, and categories
12const postFields: PostFields[] = ['title', 'content', 'categories']; // Remember to import the type PostFields to get suggestions about the post fields available and to avoid passing anything other than a possible field.
13
14const posts = await fetchPosts(3, postFields);

Each function in this module performs a fetch request to a specific WordPress API endpoint. They return a Promise that resolves with the fetched data as a JSON object or rejects with an Error if the fetch request fails.

Please refer to the source code and TypeScript type definitions for detailed information on the available functions and their parameters.

API

The package includes the following utility functions:

• configure(options):

This function sets up the package by using the provided options. It's crucial to use this function first in order to establish a connection with your Wordpress domain.

configure({BASE_URL: 'your-wordpress-domain'}).

• fetchData(endpoint?, query?):

Main function that all other utility functions use to retrieve data.

• fetchPosts(quantity?, postFields?):

Retrieve either all posts or a specified number of posts. You can specify the fields you want returned for each post.

fetchPosts(5, ['id', 'title']).

Note: fetchPosts() with no arguments will retrieve all posts with all fields. If you still want to retrieve all posts, but just with certain fields (as opposed to all of them), you can pass -1 in quantity: fetchPosts(-1, ['id', 'title'])

• fetchPostsInCategory(categoryId, postFields?, quantity?):

Retrieve posts from a specific category. You can specify the fields you want returned for each post and limit the number of posts.

fetchPostsInCategory(1, ['id', 'title'], 5).

• fetchPostBySlug(slug, postFields?):

Retrieve a post using its slug. You can specify the fields you want returned.

fetchPostBySlug('your/post-slug', ['id', 'title']).

• fetchPostById('id', postFields?):

Retrieve a post by its ID. You can specify the fields you want returned.

fetchPostById(123, ['id', 'title']).

• fetchAllCategories(categoryFields?):

Retrieve all categories. You can specify the fields you want for each category.

fetchAllCategories(['id', 'name']).

• fetchPages(quantity?, pageFields?):

Retrieve a specified number of pages. You can specify the fields you want returned for each page.

fetchPages(5, ['id', 'title']).

Note: fetchPages() with no arguments will retrieve all pages with all fields. If you still want to retrieve all pages, but just with certain fields (as opposed to all of them), you can pass -1 in quantity: fetchPages(-1, ['id', 'title'])

• fetchPageBySlug(slug, pageFields?):

Retrieve a page using its slug. You can specify the fields you want returned.

fetchPageBySlug('page-slug', ['id', 'title']).

• fetchPageById(id, pageFields?):

Retrieve a page by its ID. You can specify the fields you want returned.

fetchPageById(123, ['id', 'title']).

For more detailed information on the available functions and their parameters, please refer to the source code and TypeScript type definitions.

Importing Types

In addition to importing the functions, you can also import the Typescript types from this package. This can be useful when working with the functions and their return values in a Typescript project.

To import the types, simply include them in your import statement:

1import type { CategoryFields } from 'fetch-wordpress-api';

By importing the types, you can benefit from TypeScript's type checking and autocompletion features when using this package.

These are the types available to use in your application:

1type Post = {
2  author: number;
3  categories: number[];
4  comment_status: string;
5  content: { rendered: string };
6  date: string;
7  date_gmt: string | null | Date;
8  excerpt: { rendered: string };
9  featured_media: number;
10  format: string;
11  guid: string;
12  id: { rendered: string; raw: string };
13  link: string | Url;
14  meta: Record<string, string | number | boolean | any[] | Record<string, any>>;
15  modified: string | Date;
16  modified_gmt: string | Date;
17  ping_status: string;
18  slug: string;
19  status: string;
20  sticky: string;
21  tags: number[];
22  template: string;
23  title: { rendered: string };
24  type: string;
25};
26
27export type PostFields =
28  | 'author'
29  | 'categories'
30  | 'comment_status'
31  | 'content'
32  | 'date'
33  | 'date_gmt'
34  | 'excerpt'
35  | 'featured_media'
36  | 'format'
37  | 'guid'
38  | 'id'
39  | 'link'
40  | 'meta'
41  | 'modified'
42  | 'modified_gmt'
43  | 'ping_status'
44  | 'slug'
45  | 'status'
46  | 'sticky'
47  | 'tags'
48  | 'template'
49  | 'title'
50  | 'type';
51
52type Category = {
53  count: number;
54  description: string;
55  id: number;
56  link: string;
57  meta: Record<string, string | number | boolean | any[] | Record<string, any>>;
58  name: string;
59  slug: string;
60  taxonomy: string;
61};
62
63export type CategoryFields =
64  | 'count'
65  | 'description'
66  | 'id'
67  | 'link'
68  | 'meta'
69  | 'parent'
70  | 'name'
71  | 'slug'
72  | 'taxonomy';
73
74export type PageFields =
75  | 'author'
76  | 'comment_status'
77  | 'content'
78  | 'date'
79  | 'date_gmt'
80  | 'excerpt'
81  | 'featured_media'
82  | 'generated_slug'
83  | 'guid'
84  | 'id'
85  | 'link'
86  | 'menu_order'
87  | 'meta'
88  | 'modified'
89  | 'modified_gmt'
90  | 'password'
91  | 'permalink_template'
92  | 'ping_status'
93  | 'slug'
94  | 'status'
95  | 'template'
96  | 'title'
97  | 'type';
98
99type Page = {
100  author: number;
101  comment_status: 'open' | 'closed';
102  content: {
103    rendered: string;
104    raw?: string;
105    protected?: boolean;
106  };
107  date: string | null;
108  date_gmt: string | null;
109  excerpt: {
110    rendered: string;
111    raw?: string;
112    protected?: boolean;
113  };
114  featured_media: number;
115  generated_slug: string;
116  guid: {
117    rendered: string;
118  };
119  id: number;
120  link: string;
121  menu_order: number;
122  meta: Record<string, any>;
123  modified: string;
124  modified_gmt: string;
125  parent: number;
126  password: string;
127  permalink_template: string;
128  ping_status: 'open' | 'closed';
129  slug: string;
130  status: 'publish' | 'future' | 'draft' | 'pending' | 'private';
131  template: string;
132  title: {
133    rendered: string;
134    raw?: string;
135  };
136  type: 'page';
137};

Contributing

If you'd like to contribute to this project, please feel free to submit a pull request or open an issue on the GitHub repository.

License

This package is released under the MIT License.