feat: update so client to use api v3; add support for stack overflow enterprise; add tag and collection support (#11)

BREAKING CHANGE: stackoverflow_filter has been removed; provider configurations for default tags and team have been removed

Author: SignalRichard

.github/workflows/release.yml

@@ -43,7 +43,7 @@ jobs:
         name: Run GoReleaser
         uses: goreleaser/goreleaser-action@f82d6c1c344bcacabba2c841718984797f664a6b # v4.2.0
         with:
-          version: latest
+          version: v1.18.2
           args: release --rm-dist
         env:
           GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}

README.md

@@ -12,32 +12,25 @@ To use a released version of the Terraform provider in your environment, run `te
 
 ```terraform
 provider "stackoverflow" {
-  team_name = "my-team-name"
+  base_url = "https://api.stackoverflowteams.com/v3/teams/{team}/"
   access_token = "xxxx"
-  default_tags = ["terraform"]
-}
-
-resource "stackoverflow_filter" "filter" {
 }
 
 resource "stackoverflow_article" "article" {
   article_type = "announcement"
   title = "Terraform Provider for Stack Overflow is available!"
   body_markdown = "Look for the Stack Overflow provider in the Terraform registry"
   tags = ["example"]
-  filter = stackoverflow_filter.filter.id
 }
 
 resource "stackoverflow_question" "question" {
     title = "Stack Overflow Terraform Provider"
     body_markdown = "What is the Terraform Provider for Stack Overflow?"
     tags = ["example"]
-    filter = stackoverflow_filter.filter.id
 }
 
 resource "stackoverflow_answer" "answer" {
     question_id = stackoverflow_question.question.id
     body_markdown = "It is a Terraform plugin provider to manage resources in Stack Overflow for Teams"
-    filter = stackoverflow_filter.filter.id
 }
 ```

docs/data-sources/answer.md

@@ -15,7 +15,6 @@ The `answer` data source allows for referencing an existing answer in Stack Over
 ```
 data "stackoverflow_answer" "answer" {
     answer_id = 1
-    filter = "XXXX"
 }
 ```
 
@@ -25,10 +24,11 @@ data "stackoverflow_answer" "answer" {
 ### Required
 
 - `answer_id` (Number) The identifier for the answer
-- `filter` (String) The API filter to use
+- `question_id` (Number) The identifier for the question
 
 ### Read-Only
 
+- `body_markdown` (String) The answer content in Markdown format
 - `id` (String) The ID of this resource.
 
 

docs/data-sources/article.md

@@ -13,7 +13,6 @@ The `article` data source allows for referencing an existing article in Stack Ov
 ```
 data "stackoverflow_article" "article" {
     article_id = 1
-    filter = "XXXX"
 }
 ```
 
@@ -23,10 +22,13 @@ data "stackoverflow_article" "article" {
 ### Required
 
 - `article_id` (Number) The identifier for the article
-- `filter` (String) The API filter to use
 
 ### Read-Only
 
+- `article_type` (String) The type of article. Must be one of `knowledge-article`, `announcement`, `how-to-guide`, `policy`
+- `body_markdown` (String) The article content in Markdown format
 - `id` (String) The ID of this resource.
+- `tags` (List of String) The set of tags to be associated with the article
+- `title` (String) The title of the article
 
 

docs/data-sources/collection.md

@@ -0,0 +1,31 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "stackoverflow_collection Data Source - terraform-provider-stackoverflow"
+subcategory: ""
+description: |-
+
+---
+
+# stackoverflow_collection (Data Source)
+
+The `collection` data source allows for referencing an existing collection in Stack Overflow.
+
+```
+data "stackoverflow_collection" "collection" {
+    collection_id = 1
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `collection_id` (Number) The identifier for the collection
+
+### Read-Only
+
+- `description` (String) The collection description
+- `title` (String) The collection name
+
+

docs/data-sources/filter.md

@@ -14,7 +14,6 @@ The `question` data source allows for referencing an existing question in Stack
 
 ```
 data "stackoverflow_question" "question" {
-    filter = "XXXX"
     question_id = 1
 }
 ```
@@ -24,11 +23,13 @@ data "stackoverflow_question" "question" {
 
 ### Required
 
-- `filter` (String) The API filter to use
 - `question_id` (Number) The identifier for the question
 
 ### Read-Only
 
+- `body_markdown` (String) The question content in Markdown format
 - `id` (String) The ID of this resource.
+- `tags` (List of String) The set of tags to be associated with the article
+- `title` (String) The title of the article
 
 

docs/data-sources/question.md

@@ -0,0 +1,34 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "stackoverflow_tag Data Source - terraform-provider-stackoverflow"
+subcategory: ""
+description: |-
+
+---
+
+# stackoverflow_tag (Data Source)
+
+The `tag` data source allows for referencing an existing tag in Stack Overflow.
+
+## Example
+
+```
+data "stackoverflow_tag" "tag" {
+    tag_id = 1
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `tag_id` (Number) The identifier for the tag
+
+### Read-Only
+
+- `description` (String) The tag description
+- `id` (String) The ID of this resource.
+- `name` (String) The tag name
+
+

docs/data-sources/tag.md

@@ -6,52 +6,95 @@ description: |-
 
 ---
 
-# Stack Overflow Provider
+# stackoverflow Provider
 
-Use the Stack Overflow provider to manage questions, answers, and articles for your Stack Overflow for Teams. You must configure the provider with the proper credentials before you can use it.
+Use the Stack Overflow provider to manage questions, answers, articles, and collections for your Stack Overflow for Teams instance. You must configure the provider with the proper credentials before you can use it.
 
 ## Example Usage
 
-This example demonstrates the usage of the provider by setting up the provider configuration and several different resource types. Note the usage of the filter resource which is required when managing all other resource types.
+This example demonstrates the usage of the provider by setting up the provider configuration and several different resource types.
 
 ```terraform
 provider "stackoverflow" {
-  team_name = "my-team-name"
+  base_url = "https://api.stackoverflowteams.com/v3/teams/{team}/"
   access_token = "xxxx"
-  default_tags = ["terraform"]
 }
 
-resource "stackoverflow_filter" "filter" {
+data "stackoverflow_tag" "tag" {
+    tag_id = 1
 }
 
 resource "stackoverflow_article" "article" {
   article_type = "announcement"
   title = "Terraform Provider for Stack Overflow is available!"
   body_markdown = "Look for the Stack Overflow provider in the Terraform registry"
-  tags = ["example"]
-  filter = stackoverflow_filter.filter.id
+  tags = [data.stackoverflow_tag.tag.name]
 }
 
 resource "stackoverflow_question" "question" {
     title = "Stack Overflow Terraform Provider"
     body_markdown = "What is the Terraform Provider for Stack Overflow?"
-    tags = ["example"]
-    filter = stackoverflow_filter.filter.id
+    tags = [data.stackoverflow_tag.tag.name]
 }
 
 resource "stackoverflow_answer" "answer" {
     question_id = stackoverflow_question.question.id
     body_markdown = "It is a Terraform plugin provider to manage resources in Stack Overflow for Teams"
-    filter = stackoverflow_filter.filter.id
+}
+
+resource "stackoverflow_collection" "collection" {
+  title = "Collection Name"
+  description = "Example collection"
+  content_ids = [
+    stackoverflow_article.article.id,
+    stackoverflow_question.question.id
+  ]
 }
 ```
 
 <!-- schema generated by tfplugindocs -->
-## Argument Reference
-
-| Name | Required | Type | Environment Variable | Default | Description |
-| ---- | -------- | ---- | -------------------- | ------- | ----------- |
-| `access_token` | Required | `string` | `STACK_OVERFLOW_ACCESS_TOKEN` | | The Stack Overflow API access token |
-| `team_name` | Required | `string` | `STACK_OVERFLOW_TEAM` | | The Stack Overflow team name |
-| `base_url` | Optional | `string` | `STACK_OVERFLOW_API_URL` | `https://api.stackoverflowteams.com/2.3/` | The base URL for the Stack Overflow API |
-| `default_tags` | Optional | `string[]` | | | A list of tags to automatically associate with any resources that support tags |
+## Schema
+
+### Required
+
+- `access_token` (String) The Stack Overflow API access token. The `STACK_OVERFLOW_ACCESS_TOKEN` environment variable can be used instead.
+- `base_url` (String) The base URL for the Stack Overflow API (must end with `/`). For Stack Overflow for Teams this is in the format `https://api.stackoverflowteams.com/v3/teams/{team}/` and for Stack Overflow Enterprise this is in one of the following formats `https://{name}.stackenterprise.co/api/v3/`, `https://{name}.stackenterprise.co/api/v3/teams/{team}/`, `https://{your-custom-domain}/api/v3/`, or `https://{your-custom-domain}/api/v3/teams/{team}/`. The `STACK_OVERFLOW_API_URL` environment variable can be used instead.
+
+## Authentication and Configuration
+
+The Stack Overflow Terraform provider uses the Stack Overflow API v3 for interaction which works with the Teams Business and Enterprise tiers only.
+
+### Business
+
+Stack Overflow for Teams Business tier users should create a personal access token (PAT) using the following documentation:
+
+[https://stackoverflowteams.help/en/articles/7913768-stack-overflow-for-teams-api-v3](https://stackoverflowteams.help/en/articles/7913768-stack-overflow-for-teams-api-v3)
+
+### Enterprise
+
+Stack Overflow Enterprise users should reference the following documentation for creating API Applications/Service Keys:
+
+[https://stackoverflowteams.help/en/articles/8043418-stack-overflow-for-teams-enterprise-api-v3](https://stackoverflowteams.help/en/articles/8043418-stack-overflow-for-teams-enterprise-api-v3).
+
+API applications can be generated for users or administrators can create "service applications/keys" that are associated with the Community user which may be more appropriate in some cases.  When creating an API application, set the `Domain` to your instance's url (ex: `{name}.stackenterprise.co`)
+
+Once the API application has been registered, users should reference their site's documentation at `https://[your_site]/api/docs/authentication` for details on create an access key.  Users should follow the instructions for "Desktop Applications" that uses the implicit OAuth 2.0 flow to generate an `access_token`.
+
+> Note: The user that creates the access token will be the user referenced when creating articles, questions, and answers even if the API application is registered to the Community user.  You may wish to use another non-user account to differentiate content generated by Terraform.
+
+## Migrating from versions < 1.x
+
+Versions prior to 1.x are not considered stable and many changes have been made that will require manual interview to ensure that your upgrade is successful.
+The following is a list of features that have been removed in version 1.x:
+
+* `stackoverflow_filter` - This data/resource is no longer available in versions > 1.x because it is no longer needed. This resource was a direct requirement to using Stack Overflow's API v2.x and had no particular meaning besides configuring API access.
+* `default_tags` - Provider default tags are no longer supported. This decision was made to simplify the code base, standardize the Terraform model state to make it reflect actual configuration code, and to promote tags as first class resources. Tags are now available as data resources and can be used to ensure the resource dependency graph is more complete.
+* `team_name` - Provider team name field is no longer supported which simplifies the provider configuration to be able to support both Stack Overflow for Teams Business and Stack Overflow Enterprise tiers. Users should provide the `base_url` field and include the team name if applicable in the value.
+
+The migration steps should be as follows:
+
+1. Remove the `stackoverflow_filter` resource from code
+1. Remove the `stackoverflow_filter` resource from state by running the terraform state remove command (ex.: `terraform state rm stackoverflow_filter.filter`)
+1. Remove all usage of the `filter` field from resources
+1. Remove usage of the `default_tags` field from the provider (users may opt to use a local variable with default tags and then subsequently merge that list with each resource's tag values)
+1. Remove usage of the `team_name` field from the provider.  Users should set the `base_url` field or set the `STACK_OVERFLOW_API_URL` environment variable instead.  For example, if the previous configuration only set the `team_name` field to the value `myteam`, the `base_url` field should now be set to `https://api.stackoverflowteams.com/v3/teams/myteam/`

docs/index.md

@@ -13,17 +13,19 @@ Manages an answer and associates it to the related question.
 ## Example
 
 ```
+data "stackoverflow_tag" "tag" {
+    tag_id = 1
+}
+
 resource "stackoverflow_question" "question" {
     title = "Stack Overflow Terraform Provider"
     body_markdown = "What is the Terraform Provider for Stack Overflow?"
-    tags = ["example"]
-    filter = "XXXX"
+    tags = [data.stackoverflow_tag.tag.name]
 }
 
 resource "stackoverflow_answer" "answer" {
     question_id = stackoverflow_question.question.id
     body_markdown = "It is a Terraform plugin provider to manage resources in Stack Overflow for Teams"
-    filter = "XXXX"
 }
 ```
 
@@ -33,7 +35,6 @@ resource "stackoverflow_answer" "answer" {
 ### Required
 
 - `body_markdown` (String) The answer content in Markdown format
-- `filter` (String) The API filter to use
 - `question_id` (Number) The question identifier that this answer applies to
 
 ### Read-Only