# Over Engineering API

###### tags: `over-engineering`

## Search
GET https://over-engineering-backend.fly.dev/docs/v1/search

Run search result based on `q`.

### Request parameters
- `q`: Use the q query parameter to specify your search expression.
- `page`: The page of the search result.
- `limit`: Number of search results to return.
- `hashtags`: A List of hashtags to filter the search result.

### Response

{
    "query": "query1",
    "total": 120,
    result: [
        { 
            "position": 1,
            "title": "title1",
            "link": "http"://domain.com",
            "snippet": "snippet texts",  // BE: trim to 300chars; FE: 3 lines
            "lastmod": 1660199813, // unix time (seconds)
            "about_this_result": {
                "author": {
                    "name": "a1",
                    "link": "a1_page_link"
                },
                "series": {
                    "name": "series_name1",
                    "link": "series_link"
                },
                "hashtags": ["h1", "h2", "h3"]
                "keywords": ["k1", "k2"],
                "reading_time": 10  // number of mins
            }
            
            
        }
    ]
}

## Auto Complete
GET https://over-engineering-backend.fly.dev/docs/v1/search/auto-complete

Suggest extracted keywords (bigram) based on `q`.

- `q`: Use the q query parameter to specify your search expression.
- `max`: 0-10 auto-complete suggestions

### Response

{
    "query": "query1", 
    result: [
        { "name": "term 1", "type": "suggest1"},
        { "name": "term 2", "type": "suggest2"}
    ]
}

## Statistic: genre
GET https://over-engineering-backend.fly.dev/statistics/v1/count_by_genre

Count genre of the docs in a given year.

- `year`: the given year to count docs genre
- `top_n`: the most frequent genre

### Curl

    curl -XGET "https://over-engineering-backend.fly.dev/statistics/v1/count_by_genre?year=2020" \
         -H "Content-Type: application/json"

### Response

[
  {
    "genre": "AI & Data",
    "count": 1384
  },
  {
    "genre": "DevOps",
    "count": 692
  },
  {
    "genre": "Elastic Stack on Cloud",
    "count": 474
  },
  {
    "genre": "IoT",
    "count": 301
  }
]

## Statistic: programming languages
GET https://over-engineering-backend.fly.dev/statistics/v1/prog_lang_count

Count the most frequent programming languages of docs

- `year`: the given year to count
- `top_n`: the most frequent programming languages

### Curl

    curl -XGET "https://over-engineering-backend.fly.dev/statistics/v1/prog_lang_count?year=2019&top_n=10" \
         -H "Content-Type: application/json"

### Response

[
  {
    "prog_lang": "javascript",
    "count": 12
  },
  {
    "prog_lang": "golang",
    "count": 7
  },
  {
    "prog_lang": "html",
    "count": 7
  },
  {
    "prog_lang": "c",
    "count": 5
  },
  {
    "prog_lang": "python",
    "count": 4
  }
]

## Reference
- [Using REST to Invoke the API](https://developers.google.com/custom-search/v1/using_rest)
- [Query Parameters](https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list)
- [serpapi](https://serpapi.com/)
- [Query Suggestion Service /suggest Protocol](https://www.google.com/support/enterprise/static/gsa/docs/admin/current/gsa_doc_set/xml_reference/query_suggestion.html)