# API's for Search Thing by term

This is just related to Search API's for this page


I separate it for itens:

- SUGGESTION: My suggestions according to documentations and research about Restful API’s
- MODIFY: API that is already there but the returns need to be modified to add more information.
- CREATE: API’s that need to be create.

## SUGGESTION: Lowercase the API's

Suggestion: Endpoint lowercase: by RESTFULL API rules better be everthing in an api lowercase example ```/things/search/:offset/:searchterm```

## SUGGESTION: Responses
For all Search related API's we need the responses. But I think you are alredy doing/did this.

- 200: Successful response
- 204: No content - Successful response
- 400: Invalid or missing parameters
- 404: No found api with the provided parameters
- 500: Internal Server Error

## MODIFY: GET: Search things by offset and search term

This API is done but we need to **add** more info to the json return.

- Returns an array with things for the search term and an offset to specify the starting point from which results should be retrieved.
- Endpoint: ```/things/search/:offset/:searchterm```

### Return JSON for the object inside the array

In thie API we need to add ```id, association, keywords, contributors```
fo the JSON.

(The *** it means that the value need to be added in the API, the rest is alredy there.)

[{
    "thingid": "https://repository.tudelft.nl/Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5",
    "title": "Possibilities, Intentions and Threats",
    "sub_title": "Dual Use in the Life Sciences Reconsidered",
    "description": "description ",
    "object_type": "journal article",
    "Year of publictation": "year of publications in the journal",
    "date_created": "2016-04-25 13:21:21.666000",
    "date_modified": "2019-10-01 14:58:07.520000",
    "embargo": "",
    "access_type": "",
    "access_value": "© 2011 Van der Bruggen, K.; This article is published with open access at Springerlink.com",
    "***id": "Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5", // this is the thingid without https://repository.tudelft.nl/
    "***organization":
        {
            "Faculty": "TU Delft",
            "Department": "Industrial Design"
            "ResearchGroup": "Sustainable Materials"
        }
    "***keywords": "ARRAY IN SUBJECTS",
    "***contributors": [
        {
            "index": "0",
            "contributor_role": "author",
            "person": "Person_7f871638-d510-4703-9028-4be4ff75723a",
            "name_part": "K.",
            "first_name": "K.",
            "last_name": "Van der Bruggen",
            "things": [
                "Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5"
            ],
            "***affiliation": // here we need to bring the assocuiation for each person (if the person has before 2016 the repo don't have ths info)
            {
                "Faculty": "TU Delft",
                "Department": "Aerospace Engineering",
                "ResearchGroup": "Planetary Exploration"
            }

        },
        {
            "index": "0",
            "contributor_role": "author",
            "person": "Person_7f871638-d510-4703-9028-4be4ff75723a",
            "name_part": "K.",
            "first_name": "K.",
            "last_name": "Another name",
            "things": [
                "Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5"
            ],
            "***affiliation": 
            {
                "Faculty": "TU Delft",
                "Department": "Aerospace Engineering",
                "ResearchGroup": "Air Transport & Operations"
            }

        }
    ]
}],

#### Explanation for departments:
We need to bring the association/department here, so departments will be an object as followed:

{
 "Faculty" : "TU Delft",
 "Department" : "Industrial Design"
 "ResearchGroup": "Sustainable Materials"
}

Might be the record does not have this info, or have it partially. In case partially brings the info that we have available:

{
 "Faculty" : "TU Delft",
 "Department" : "Industrial Design"
}

In case empty, bring an empty object:

`{}`

#### Explanation for contributors:

We need to bring contributors, but is also inportant that we add association for each contributors in this return

"contributors": [
    {
        "index": "0",
        "contributor_role": "author",
        "person": "Person_7f871638-d510-4703-9028-4be4ff75723a",
        "name_part": "K.",
        "first_name": "K.",
        "last_name": "Van der Bruggen",
        "things": [
            "Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5"
        ],
        "association": 
        {
            "Faculty": "TU Delft",
            "Department": "Aerospace Engineering",
            "ResearchGroup": "Planetary Exploration"
        }

    },

Not all person has this info. For persons before 2016 the repo do not have this info so we bring association as an empty object.

"contributors": [
    {
        "index": "0",
        "contributor_role": "author",
        "person": "",
        "name_part": "K.",
        "first_name": "K.",
        "last_name": "Van der Bruggen",
        "things": [
            "Thing_0026f5ff-8f06-4bd7-92aa-503eeb7955f5"
        ],
        "association": {}

    },

## CREATE: API's for count by filter

Here we have two options

Create a ```Unified API for counts``` OR create a ```API's for count by filter```

The unified APIwill be responsible to bring all counts for a serch term and an unique json format. We also can have separate API's for count for each filter (API's for count by filter).

I dont kno which of the two option makes more sense in term of perfomance, but we need the information of the count every time we do a serach term, so if we do separate we need to call all apis every time. Thus I think makes more sense to have an unified one.

This is the image of the filter menu where we will need the the json with the counts :


### Unified API for counts

One API that brings all the counts:

- GET: Number of and Keywords in search term results
- GET: Number of things in Embargo in a search term results
- GET: Number of things metadataOnly in a search term results
- GET: Number of things openAccess in a search term results
- GET: Number of languages present in search term results
- GET: Number of Object Types present in search term results

**Endpoint**

- Endpoint:``` /things/search/count/{searchTerm}```
- Usage: ```/things/search/count/computer```

**Response Format**

{
"keywords": [
  {
    "word": "computer",
    "count": 25
  },
  {
    "word": "technology",
    "count": 15
  },
  {
    "word": "software",
    "count": 8
  },
  {
    "word": "hardware",
    "count": 5
  }
],
"embargoCount":2,
"metadataOnlyCount":2,
"openAccessCount":2,
"languages": [
  {
    "language": "en",
    "count": 2
  },
  {
    "language": "nl",
    "count": 5
  },
]
"objectTypes": [
  {
    "objectType": "Journal",
    "count": 2
  },
  {
    "objectType": "books",
    "count": 5
  },
]

### API's for count by filter

**OR** we can go with one API for count by filter, if so, as the folowed....

### Keywords

#### GET: NUmber of and Keywords in search term results
- Returns: List of keywords present in the search results along with their counts (how many things has that word in their keywords).
- Endpoint: ```/things/search/keyword/count/{searchTerm}```
- Example Usage: ```/things/search/keyword/count/computer```

**Response format**

"keywords": [
  {
    "word": "computer",
    "count": 25
  },
  {
    "word": "technology",
    "count": 15
  },
  {
    "word": "software",
    "count": 8
  },
  {
    "word": "hardware",
    "count": 5
  }
]

### Embargo

#### GET: Number of things in Embargo in a search term results

- Returns the Number of records under embargo present in the search results.
- Endpoint: ```/things/search/embargo/count/{searchTerm}```
- Example Usage: ```/things/search/embargo/count/computer```

{
    "embargoCount":2
}

### Metadata only

Metadata only is the list of records without any file (metadataOnly)in the search results.

#### GET: Number of things metadataOnly in a search term results

- Returns the Number of records without files present in the search results.
- Endpoint: ```/things/search/metadataOnly/count/{searchTerm}```
- Example Usage: ```/things/search/metadataOnly/count/computer```

{
    "metadataOnlyCount": 4
}

### Open Access

Open Access are records with files that are not under embargo.

#### GET: Number of things openAccess in a search term results

- Returns the Number of things with files and not under embargo
- Endpoint: ```/things/search/openAccess/count/{searchTerm}```
- Example Usage: ```/things/search/openAccess/count/computer```

{
    "openAccessCount": 1
}

### Languages

#### GET: Number of languages present in search term results

- Returns the Number of things under a certain language in the search results along with the language itself
- Endpoint: ```/things/search/language/count/{searchTerm}```
- Example Usage: ```/things/search/language/count/computer```

"languages": [
  {
    "language": "en",
    "count": 2
  },
  {
    "language": "nl",
    "count": 5
  },
]

### Object Type

#### GET: Number of Object Types present in search term results

- Returns the Number of things under a certain object types in the search results along with the object types itself
- Endpoint: ```/things/search/objectType/count/{searchTerm}```
- Example Usage: ```/things/search/objectType/count/computer```

"objectTypes": [
  {
    "objectType": "Journal",
    "count": 2
  },
  {
    "objectType": "books",
    "count": 5
  },
]

## CREATE: API's for list by filter

### Keywords

#### GET: List of things with thta keywords in search term results
- Returns: List of things by keywords present in the search results.
- Endpoint: ```/things/search/keyword/{offset}/{searchTerm}/{keyword}```
- Example Usage: ```/things/search/keyword/10/computer/technology```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Embargo

#### GET: List of things under Embargo in search term results
- Returns a List of records under embargo present in the search results.
- Endpoint: ```/things/search/embargo/{offset}/{searchTerm}```
- Example Usage: ```/things/search/embargo/10/computer```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Metadata only

Metadata only is the list of records without any file (metadataOnly)in the search results.

#### GET: Number of things metadataOnly in a search term results

- Returns the Number of records without files present in the search results.
- Endpoint: ```/things/search/metadataOnly/count/{searchTerm}```
- Example Usage: ```/things/search/metadataOnly/count/computer```

{
    "metadataOnlyCount": 4
}

#### GET: List of things metadataOnly in search term results
- Returns a List of records under embargo present in the search results.
- Endpoint: ```/things/search/metadataOnly/{offset}/{searchTerm}```
- Example Usage: ```/things/search/metadataOnly/10/computer```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Open Access

Open Access are records with files that are not under embargo.

#### GET: List of things openAccess in search term results
- Returns a List of things with files and not under embargo .
- Endpoint: ```/things/search/openAccess/{offset}/{searchTerm}```
- Example Usage: ```/things/search/openAccess/10/computer```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Languages

#### GET: List of things under a certain langage in search term results
- Returns a List of things with files and not under embargo .
- Endpoint: ```/things/search/language/{offset}/{searchTerm}/{language}```
- Example Usage: ```/things/search/language/10/computer/nl```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Object Type

#### GET: List of things under a certain objectType in search term results
- Returns a List of things with files and not under embargo .
- Endpoint: ```/things/search/objectType/{offset}/{searchTerm}/{objectType}```
- Example Usage: ```/things/search/objectType/10/computer/books```

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

### Data Range

#### GET: Things by date range in Search term results
- Returns a List of things with files and not under embargo .
- Endpoint: /things/search/dateRange/{offset}/{searchTerm}/{startDate}/{endDate}
- Example Usage: /things/search/dateRange/10/computer/2022-01-01/2022-12-31

**Response format**

Same response format json of ```/Thing/Search/{offset}/{searchterm})```

[
    {"thig object 01"},
    {"thig object 01"}
]

## SUGGESTION: Modify API for GET Number of total things by search term

I suggest to modify this to follow the same pattern of counts API's. Currently it is the API ``` /Thing/SearchTotal/{searchterm}```

- Returns total number Things that contain searchterm
- Suggested Endpoint: ```/things/search/count/{searchTerm}```
- Example Usage: ```/things/search/count/computer```