diff --git a/README.md b/README.md index 0c03a58..6055050 100644 --- a/README.md +++ b/README.md @@ -21,25 +21,7 @@ Built with [NestJS framework](https://nestjs.com) and writen in TypeScript. [Pri - [Getting Started](#getting-started) - [Data](#data) -- [API Endpoint](#api-endpoint) - - [Documentation](#documentation) - - [Get provinces](#get-provinces) - - [Get specific province](#get-specific-province) - - [Get regencies by name](#get-regencies-by-name) - - [Get specific regency](#get-specific-regency) - - [Get all regencies in a province](#get-all-regencies-in-a-province) - - [Get districts by name](#get-districts-by-name) - - [Get specific district](#get-specific-district) - - [Get all districts in a regency](#get-all-districts-in-a-regency) - - [Get villages by name](#get-villages-by-name) - - [Get specific village](#get-specific-village) - - [Get all villages in a district](#get-all-villages-in-a-district) - - [Get islands by name](#get-islands-by-name) - - [Get specific island](#get-specific-island) - - [Get all islands in a regency](#get-all-islands-in-a-regency) -- [Query Parameters](#query-parameters) - - [`sortBy`](#sortby) - - [`sortOrder`](#sortorder) +- [Documentation](#documentation) - [Live Demo](#live-demo) - [Contributing](#contributing) - [Problem Reporting](#problem-reporting) @@ -60,235 +42,11 @@ The data we used is based on official sources, managed in [**idn-area-data**](ht > The [data](https://github.com/fityannugroho/idn-area-data/tree/main/data) is made available here under the [Open Database License (ODbL)](https://github.com/fityannugroho/idn-area-data/blob/main/data/LICENSE.md). -## API Endpoint +## Documentation -[sortby-query]: #sortby -[sortorder-query]: #sortorder +Read the latest version of API documentation in the [documentation page](https://idn-area.cyclic.app/docs). This documentation is automatically generated using [`@nestjs/swagger`](https://docs.nestjs.com/openapi/introduction). -### Documentation - -``` -GET /docs -``` - -- Use this endpoint to get generated **API documentation**. - -### Get provinces - -``` -GET /provinces -``` - -- Use this endpoint to **get all of provinces**. -- This endpoint will return an array of province. -- Usage example: http://localhost:3000/provinces - -**Filter Provinces by `name`** - -``` -GET /provinces?name={provinceName} -``` - -- Add `name` query to **filter the provinces by its name**. -- For example, if you replace the `{provinceName}` with "jawa" then you will get all the provinces whose names contain the word "jawa". -- The `{provinceName}` must be **at least 3 characters**, maximum 255 characters, and does not contains any symbols. If not, you will get `400 Bad Request` response. -- The response will be an **empty array** `[]` if there are no province matched with the `{provinceName}`. -- Usage example: http://localhost:3000/provinces?name=jawa - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get specific province - -``` -GET /provinces/{provinceCode} -``` - -- Use this endpoint to **get a specific province**. -- The `{provinceCode}` must be **2 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the province with the same code as `{provinceCode}`. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/provinces/32 - -### Get regencies by name - -``` -GET /regencies?name={regencyName} -``` - -- Use this endpoint to **get the regencies by its name**. -- The `{regencyName}` **is required** and must be **at least 3 characters**, maximum 255 characters, and does not contains any symbols. If not, you will get `400 Bad Request` response. -- This endpoint **will return** an array of regency. -- Usage example: http://localhost:3000/regencies?name=bandung - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get specific regency - -``` -GET /regencies/{regencyCode} -``` - -- Use this endpoint to **get a specific regency**. -- The `{regencyCode}` must be **4 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the regency with the same code as `{regencyCode}`. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/regencies/3273 - -### Get all regencies in a province - -``` -GET /provinces/{provinceCode}/regencies -``` - -- Use this endpoint to **get all regencies in a province**. -- The `{provinceCode}` must be **2 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the array of regency if the `{provinceCode}` is exists. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/provinces/32/regencies - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get districts by name - -``` -GET /districts?name={districtName} -``` - -- Use this endpoint to **get the districts by its name**. -- The `{districtName}` **is required** and must be **at least 3 characters**, maximum 255 characters, and does not contains any other symbols besides `'()-./`. If not, you will get `400 Bad Request` response. -- This endpoint **will return** an array of district, or an **empty array** `[]` if there are no district matched with the `{districtName}`. -- Usage example: http://localhost:3000/districts?name=regol - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get specific district - -``` -GET /districts/{districtCode} -``` - -- Use this endpoint to **get a specific district**. -- The `{districtCode}` must be **6 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the district with the same code as `{districtCode}`. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/districts/327311 - -### Get all districts in a regency - -``` -GET /regencies/{regencyCode}/districts -``` - -- Use this endpoint to **get all districts in a regency**. -- The `{regencyCode}` must be **4 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the array of district if the `{regencyCode}` is exists. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/regencies/3273/districts - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get villages by name - -``` -GET /villages?name={villageName} -``` - -- Use this endpoint to **get the villages by its name**. -- The `{villageName}` **is required** and must be **at least 3 characters**, maximum 255 characters, and does not contains any other symbols besides `'()-./`. If not, you will get `400 Bad Request` response. -- This endpoint **will return** an array of village, or an **empty array** `[]` if there are no village matched with the `{villageName}`. -- Usage example: http://localhost:3000/villages?name=balong - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get specific village - -``` -GET /villages/{villageCode} -``` - -- Use this endpoint to **get a specific village**. -- The `{villageCode}` must be **10 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the village with the same code as `{villageCode}`. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/villages/3273111004 - -### Get all villages in a district - -``` -GET /districts/{districtCode}/villages -``` - -- Use this endpoint to **get all villages in a district**. -- The `{districtCode}` must be **6 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the array of village if the `{districtCode}` is exists. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/districts/327311/villages - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get islands by name - -``` -GET /islands?name={islandName} -``` - -- Use this endpoint to **get the islands by its name**. -- The `{islandName}` **is required** and must be **at least 3 characters**, maximum 255 characters, and does not contains any other symbols besides `'-/`. If not, you will get `400 Bad Request` response. -- This endpoint **will return** an array of island, or an **empty array** `[]` if there are no island matched with the `{islandName}`. -- Usage example: http://localhost:3000/islands?name=java - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -### Get specific island - -``` -GET /islands/{islandCode} -``` - -- Use this endpoint to **get a specific island**. -- The `{islandCode}` must be **9 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the island with the same code as `{islandCode}`. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/islands/110140001 - -### Get all islands in a regency - -``` -GET /regencies/{regencyCode}/islands -``` - -- Use this endpoint to **get all islands in a regency**. -- The `{regencyCode}` must be **4 numeric characters**. If not, you will get `400 Bad Request` response. -- This endpoint **will return** the array of island if the `{regencyCode}` is exists. Otherwise, you will get a `404 Not Found` response. -- Usage example: http://localhost:3000/regencies/1101/islands - -> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries. - -## Query Parameters - -You can use query parameters to control what data is returned in endpoint responses. - -### `sortBy` - -``` -GET /...?sortBy={code|name} -``` - -- Add `sortBy` query to **sorting the result** by `code` or `name`. -- The `sortBy` **can only be filled** by `code` or `name`. If not, you will get `400 Bad Request` response. -- If `sortBy` **is not set**, sorting will be done by the `code`. -- Usage example : - - At [`provinces`](#get-provinces) endpoint: http://localhost:3000/provinces?sortBy=name - - At [`regencies`](#get-regencies-by-name) endpoint: http://localhost:3000/regencies?name=bandung&sortBy=code - -### `sortOrder` - -``` -GET /...?sortOrder={asc|desc} -``` - -- Add `sortOrder` query to **specify the sort order** whether ascending `asc` or descending `desc`. -- The `sortOrder` **can only be filled** by `asc` or `desc`. If not, you will get `400 Bad Request` response. -- If `sortOrder` **is not set**, sorting will be done in `asc` order. -- Usage example : - - At [`districts`](#get-districts-by-name) endpoint: http://localhost:3000/districts?name=regol&sortOrder=desc - - At [`villages`](#get-villages-by-name) endpoint: http://localhost:3000/villages?name=balong&sortOrder=asc - -> These queries can be combined with other queries linked by `&` character. -> -> For example : http://localhost:3000/provinces?name=jawa&sortBy=name&sortOrder=asc +> You also can access the documentation in your local machine by running the app (see [Getting Started](#getting-started)) and open http://localhost:3000/docs in your browser. ## Live Demo