From 51a765ae72ade8e446f885d0a93f8df6fe2c7fa0 Mon Sep 17 00:00:00 2001 From: Noah Schechter <100018299+noah-schechter@users.noreply.github.com> Date: Mon, 2 Sep 2024 06:54:01 +0000 Subject: [PATCH 1/5] Add in-platform API docs --- .../api_documentation_component.ex | 186 ++++++++++++++++++ .../platform_web/live/projects_live/show.ex | 5 + 2 files changed, 191 insertions(+) create mode 100644 platform/lib/platform_web/live/projects_live/api_documentation_component.ex diff --git a/platform/lib/platform_web/live/projects_live/api_documentation_component.ex b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex new file mode 100644 index 000000000..ba92f64d5 --- /dev/null +++ b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex @@ -0,0 +1,186 @@ +defmodule PlatformWeb.ProjectLive.APIDoc do + use PlatformWeb, :live_component + + alias Platform.Projects + alias Platform.Material.Attribute + + def update(%{project: project} = assigns, socket) do + IO.inspect(project.name) + attributes = Platform.Material.Attribute.active_attributes(project: project) + attribute_labels = Map.new(attributes, &{&1.name, &1.label}) + + grouped_attributes = group_attributes(attributes, project) + + {:ok, + socket + |> assign(assigns) + |> assign(:grouped_attributes, grouped_attributes) + |> assign(:attribute_labels, attribute_labels) + |> assign(:project, project)} + end + + def render(assigns) do + ~H""" +
+
+

API Details

+

+ The Atlos API uses API-specific identifers, rather than interface names, to refer to attributes, metadata, and even the project itself. Learn more in our + + + API documentation. + + +

+
+
+
+
+
+
+
+
+
+
+
+
+ Interface Name +
+
+ API Identifier +
+
+
+
+ <%= for {group, attributes} <- @grouped_attributes do %> +
+
+ <%= if group != :core_and_unassigned do %> +
+

+ + <%= cond do %> + <% group == :metadata -> %> + Metadata + <% group == :project -> %> + Project + <% true -> %> + <%= group.name %> + <% end %> + +

+

+ <%= cond do %> + <% group == :metadata -> %> + Use the API to access or update incident metadata in the same way as other attributes. + <% group == :project -> %> + Use this identifier to refer to this project in the API. + <% true -> %> + <%= group.description %> + <% end %> +

+
+ <% end %> +
+ <%= for attribute <- attributes do %> +
+
+
+ <%= if attribute == @project, + do: attribute.name, + else: attribute.label %> +
+
+
+ +
+
+
+
+ <% end %> +
+
+
+ <% end %> +
+
+
+
+
+
+
+
+
+
+ """ + end + + defp group_attributes(attributes, project) do + core_attributes = Enum.filter(attributes, &(is_atom(&1.name) and &1.pane != :metadata)) + + ## Sort metadata alphabetically, because it doesn't have a custom order + metadata_attributes = + Enum.sort_by(Enum.filter(attributes, &(&1.pane == :metadata)), & &1.label) + + custom_attributes = Enum.reject(attributes, &(is_atom(&1.name) or &1.pane == :metadata)) + + groups = project.attribute_groups || [] + + grouped = + Enum.map(groups, fn group -> + attributes = Enum.filter(custom_attributes, &(&1.name in group.member_ids)) + {group, attributes} + end) + + unassigned_attributes = + Enum.reject(custom_attributes, fn attr -> + Enum.any?(groups, &(attr.name in &1.member_ids)) + end) + + [ + {:core_and_unassigned, core_attributes ++ unassigned_attributes} + ] ++ + grouped ++ + [ + {:metadata, metadata_attributes} + ] ++ + [ + {:project, [project]} + ] + end + + defp get_group_color(group) do + cond do + group == :metadata -> + "#f87171" + + group == :project -> + "#000000" + + true -> + group.color + end + end +end diff --git a/platform/lib/platform_web/live/projects_live/show.ex b/platform/lib/platform_web/live/projects_live/show.ex index 4708c660b..636346e57 100644 --- a/platform/lib/platform_web/live/projects_live/show.ex +++ b/platform/lib/platform_web/live/projects_live/show.ex @@ -369,6 +369,11 @@ defmodule PlatformWeb.ProjectsLive.Show do <% end %> + <.live_component + module={PlatformWeb.ProjectLive.APIDoc} + id="api-documentation_component" + project={@project} + /> <% end %> <%= if @live_action == :deleted and Permissions.can_view_project_deleted_media?(@current_user, @project) do %> <.live_component From 6ecb3db869927e287e65a8088d26259bea5568ef Mon Sep 17 00:00:00 2001 From: Noah Schechter <100018299+noah-schechter@users.noreply.github.com> Date: Mon, 2 Sep 2024 06:57:24 +0000 Subject: [PATCH 2/5] Cleanup --- .../live/projects_live/api_documentation_component.ex | 2 -- 1 file changed, 2 deletions(-) diff --git a/platform/lib/platform_web/live/projects_live/api_documentation_component.ex b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex index ba92f64d5..b7dff3b27 100644 --- a/platform/lib/platform_web/live/projects_live/api_documentation_component.ex +++ b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex @@ -5,10 +5,8 @@ defmodule PlatformWeb.ProjectLive.APIDoc do alias Platform.Material.Attribute def update(%{project: project} = assigns, socket) do - IO.inspect(project.name) attributes = Platform.Material.Attribute.active_attributes(project: project) attribute_labels = Map.new(attributes, &{&1.name, &1.label}) - grouped_attributes = group_attributes(attributes, project) {:ok, From 504e3aaa5d8b4995686e9566d4442f1c8c4eb079 Mon Sep 17 00:00:00 2001 From: noah-schechter Date: Mon, 2 Sep 2024 00:03:42 -0700 Subject: [PATCH 3/5] Update docs site --- docs/content/docs/Technical/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/Technical/api.md b/docs/content/docs/Technical/api.md index a10f95ebe..60d4e9388 100644 --- a/docs/content/docs/Technical/api.md +++ b/docs/content/docs/Technical/api.md @@ -168,11 +168,11 @@ requests.post( ``` ### Update an incident's attribute value -`POST /api/v2/update/:slug/:attribute_name` updates the attribute `:attribute_name` in the incident with slug `:slug`. It has two parameters: +`POST /api/v2/update/:slug/:attribute_identifier` updates the attribute `:attribute_identifier` in the incident with slug `:slug`. It has two parameters: - `value`, the new value of the attribute (required). For text or single-select attributes, `value` should be a string. For multi-select attributes, `value` should be a list of strings. - `message`, a string to be displayed as an explanation for the update (optional). If `message` is provided, it will be added as a comment to the incident (as part of the tracked change). -The `:attribute_name` may not be the name of the attribute displayed in the interface: +You can find the `:attribute_identifier` in the **Access** pane of your project. Attribute's names in the Atlos interface are different from their API identifiers: - Core attributes have string names (such as `description` and `status`). - Custom attributes are identified by a long ID. From 249ade3ebbe4084624626438536be0c98773c987 Mon Sep 17 00:00:00 2001 From: Noah Schechter <100018299+noah-schechter@users.noreply.github.com> Date: Mon, 2 Sep 2024 07:17:51 +0000 Subject: [PATCH 4/5] Don't show project's ID --- .../api_documentation_component.ex | 59 ++++++------------- 1 file changed, 19 insertions(+), 40 deletions(-) diff --git a/platform/lib/platform_web/live/projects_live/api_documentation_component.ex b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex index b7dff3b27..ffb89c8e3 100644 --- a/platform/lib/platform_web/live/projects_live/api_documentation_component.ex +++ b/platform/lib/platform_web/live/projects_live/api_documentation_component.ex @@ -13,8 +13,7 @@ defmodule PlatformWeb.ProjectLive.APIDoc do socket |> assign(assigns) |> assign(:grouped_attributes, grouped_attributes) - |> assign(:attribute_labels, attribute_labels) - |> assign(:project, project)} + |> assign(:attribute_labels, attribute_labels)} end def render(assigns) do @@ -62,31 +61,26 @@ defmodule PlatformWeb.ProjectLive.APIDoc do class={"px-6 flex flex-col #{if group != :core_and_unassigned, do: "pb-1 pt-5"}"} style={ if group != :core_and_unassigned, - do: "border-left: 4px solid #{get_group_color(group)};" + do: + "border-left: 4px solid #{if group == :metadata, do: "#000000", else: group.color};" } > <%= if group != :core_and_unassigned do %>

- - <%= cond do %> - <% group == :metadata -> %> - Metadata - <% group == :project -> %> - Project - <% true -> %> - <%= group.name %> + + <%= if group == :metadata do %> + Metadata + <% else %> + <%= group.name %> <% end %>

- <%= cond do %> - <% group == :metadata -> %> - Use the API to access or update incident metadata in the same way as other attributes. - <% group == :project -> %> - Use this identifier to refer to this project in the API. - <% true -> %> - <%= group.description %> + <%= if group == :metadata do %> + Use the API to access or update incident metadata in the same way as other attributes. + <% else %> + <%= group.description %> <% end %>

@@ -96,9 +90,12 @@ defmodule PlatformWeb.ProjectLive.APIDoc do
- <%= if attribute == @project, - do: attribute.name, - else: attribute.label %> + <%= if attribute.parent do %> + + <%= @attribute_labels[attribute.parent] %>: + + <% end %> + <%= attribute.label %>
@@ -109,9 +106,7 @@ defmodule PlatformWeb.ProjectLive.APIDoc do type="button" x-on:click={"window.setClipboard(#{Jason.encode!(attribute.name)}); pulse = true; setTimeout(() => pulse = false, 500)"} > - <%= if attribute == @project, - do: attribute.id, - else: attribute.name %> + <%= attribute.name %>
@@ -163,22 +158,6 @@ defmodule PlatformWeb.ProjectLive.APIDoc do grouped ++ [ {:metadata, metadata_attributes} - ] ++ - [ - {:project, [project]} ] end - - defp get_group_color(group) do - cond do - group == :metadata -> - "#f87171" - - group == :project -> - "#000000" - - true -> - group.color - end - end end From ba8f9e77a3de585f2523784405b98cef2f100a8a Mon Sep 17 00:00:00 2001 From: noah-schechter Date: Mon, 2 Sep 2024 00:18:39 -0700 Subject: [PATCH 5/5] Fix plurals --- docs/content/docs/Technical/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/Technical/api.md b/docs/content/docs/Technical/api.md index 60d4e9388..3a1bacdaa 100644 --- a/docs/content/docs/Technical/api.md +++ b/docs/content/docs/Technical/api.md @@ -172,7 +172,7 @@ requests.post( - `value`, the new value of the attribute (required). For text or single-select attributes, `value` should be a string. For multi-select attributes, `value` should be a list of strings. - `message`, a string to be displayed as an explanation for the update (optional). If `message` is provided, it will be added as a comment to the incident (as part of the tracked change). -You can find the `:attribute_identifier` in the **Access** pane of your project. Attribute's names in the Atlos interface are different from their API identifiers: +You can find the `:attribute_identifier` in the **Access** pane of your project. Attributes' names in the Atlos interface are different from their API identifiers: - Core attributes have string names (such as `description` and `status`). - Custom attributes are identified by a long ID.