대부분의 node는 API의 GUI(그래픽 사용자 인터페이스) 표현입니다. 인터페이스를 설계한다는 것은 API 엔드포인트와 파라미터를 사용자 친화적인 방식으로 표현하는 방법을 찾는 것을 의미합니다. 전체 API를 node의 양식 필드로 직접 변환하면 좋은 사용자 경험을 제공하지 못할 수 있습니다.

이 문서는 따라야 할 설계 지침과 표준을 제공합니다. 이 가이드라인은 n8n에서 사용하는 것과 동일합니다. 이는 커뮤니티 node와 내장 node를 혼용하는 사용자에게 원활하고 일관된 사용자 경험을 제공하는 데 도움이 됩니다.

설계 지침#

모든 node는 n8n의 node UI 요소를 사용하므로 색상, 테두리 등 스타일 세부 사항을 고려할 필요가 없습니다. 그러나 기본 설계 프로세스를 거치는 것은 여전히 유용합니다:

• 통합 중인 API 문서를 검토합니다. 스스로에게 다음을 물어보세요:
  • 무엇을 생략할 수 있나요?
  • 무엇을 단순화할 수 있나요?
  • API의 어떤 부분이 혼란스럽나요? 사용자가 이해하는 데 어떻게 도울 수 있나요?
• 와이어프레임 도구를 사용하여 필드 레이아웃을 시험해 봅니다. node에 필드가 많고 혼란스러워지는 경우 필드 표시 및 숨기기에 관한 n8n의 지침을 고려하세요.

표준#

UI 텍스트 스타일#

UI 텍스트 용어#

• node가 연결하는 서비스와 동일한 용어를 사용합니다. 예를 들어, Notion node는 Notion 블록을 Notion 단락이 아닌 블록이라고 불러야 합니다. Notion이 이 요소를 블록이라고 부르기 때문입니다. 이 규칙에는 예외가 있으며, 보통 기술 용어를 피하기 위한 것입니다(예: upsert 오퍼레이션 이름 및 설명에 관한 지침 참고).
• 서비스가 API와 GUI에서 동일한 것에 대해 다른 용어를 사용하는 경우가 있습니다. 대부분의 사용자가 친숙한 것이므로 node에서는 GUI 언어를 사용합니다. 일부 사용자가 서비스의 API 문서를 참조해야 할 수 있다고 생각되면 힌트에 이 정보를 포함하는 것을 고려하세요.
• 더 간단한 대안이 있는 곳에 기술 용어를 사용하지 마세요.
• 이름 지정 시 일관성을 유지하세요. 예를 들어, directory 또는 folder 중 하나를 선택하고 그것을 고수하세요.

Node 명명 규칙#

필드 표시 및 숨기기#

필드는 다음 중 하나일 수 있습니다:

• node가 열릴 때 표시됨: 리소스, 오퍼레이션 및 필수 필드에 사용합니다.
• 사용자가 해당 섹션을 클릭할 때까지 Optional fields 섹션에 숨겨짐: 선택적 필드에 사용합니다.

점진적으로 복잡성을 공개합니다: 이전 필드에 값이 있을 때까지 해당 필드에 의존하는 필드를 숨깁니다. 예를 들어, Filter by date 토글과 Date to filter by 날짜 선택기가 있는 경우 사용자가 Filter by date를 활성화할 때까지 Date to filter by를 표시하지 않습니다.

필드 유형별 규칙#

자격 증명#

n8n은 자격 증명 필드를 node의 상단 필드로 자동 표시합니다.

리소스와 오퍼레이션#

API는 일반적으로 데이터에 무언가를 수행하는 것을 포함합니다. 예를 들어, "get all tasks". 이 예에서 "task"는 리소스이고 "get all"은 오퍼레이션입니다.

node에 이 리소스와 오퍼레이션 패턴이 있는 경우 첫 번째 필드는 Resource이고 두 번째 필드는 Operation이어야 합니다.

필수 필드#

필드 순서:

• 가장 중요한 것부터 덜 중요한 것 순서.
• 범위: 넓은 것부터 좁은 것 순서. 예를 들어, Document, Page, Text to insert 필드가 있으면 그 순서로 배치합니다.

선택적 필드#

• 알파벳 순서로 필드를 정렬합니다. 유사한 것들을 그룹화하려면 이름을 바꿀 수 있습니다. 예를 들어, Email과 Secondary Email을 **Email (primary)**와 **Email (secondary)**로 이름을 바꿉니다.
• 선택적 필드에 값이 설정되지 않았을 때 node가 사용하는 기본값이 있다면 해당 값으로 필드를 로드합니다. 필드 설명에 이를 설명합니다. 예를 들어, Defaults to false.
• 연결된 필드: 하나의 선택적 필드가 다른 필드에 의존하는 경우 함께 묶습니다. 선택 시 두 필드를 모두 표시하는 단일 옵션 아래에 있어야 합니다.
• 선택적 필드가 많은 경우 주제별로 그룹화하는 것을 고려합니다.

도움말#

GUI에는 5가지 유형의 도움말이 내장되어 있습니다:

• 정보 박스: 필드 사이에 나타나는 노란 박스. 자세한 내용은 UI 요소 | Notice를 참고하세요.
  • 필수 정보에 정보 박스를 사용합니다. 남용하지 마세요. 드물게 만들면 더 눈에 띄고 사용자의 주의를 끕니다.
• 파라미터 힌트: 사용자 입력 필드 아래에 표시되는 텍스트 줄. 사용자가 알아야 할 내용이 있지만 정보 박스가 과하다고 느껴질 때 사용합니다.
• Node 힌트: 입력 패널, 출력 패널 또는 node 세부 정보 보기에서 도움말을 제공합니다. 자세한 내용은 UI 요소 | Hints를 참고하세요.
• 툴팁: 사용자가 툴팁 아이콘 에 마우스를 올릴 때 나타나는 콜아웃. 사용자가 필요로 할 수 있는 추가 정보에 툴팁을 사용합니다.
  • 모든 필드에 툴팁을 제공할 필요는 없습니다. 유용한 정보를 포함하는 경우에만 추가합니다.
  • 툴팁을 작성할 때 사용자가 필요로 하는 것을 생각합니다. API 파라미터 설명을 그대로 복사 붙여넣기 하지 마세요. 설명이 의미가 없거나 오류가 있으면 개선합니다.
• 플레이스홀더 텍스트: n8n은 사용자가 값을 입력하지 않은 필드에 플레이스홀더 텍스트를 표시할 수 있습니다. 이는 사용자가 해당 필드에서 기대하는 것을 알 수 있도록 도움이 됩니다.

정보 박스, 힌트, 툴팁은 더 많은 정보에 대한 링크를 포함할 수 있습니다.

오류#

어떤 필드가 필수인지 명확히 합니다.

가능한 경우 필드에 유효성 검사 규칙을 추가합니다. 예를 들어, 필드에 이메일이 예상되는 경우 유효한 이메일 패턴을 확인합니다.

오류를 표시할 때 빨간 오류 제목에는 주요 오류 메시지만 표시되도록 합니다. 추가 정보는 Details에 들어가야 합니다.

자세한 내용은 Node 오류 처리를 참고하세요.

토글#

• 이진 상태에 대한 툴팁은 Whether to . . . 와 같은 것으로 시작해야 합니다.
• 목록이 토글보다 필요할 수 있습니다:
  • false 상태에서 무슨 일이 일어나는지 명확할 때 토글을 사용합니다. 예를 들어, Simplify Output?. 대안(출력 단순화하지 않음)이 명확합니다.
  • 더 명확성이 필요할 때 명명된 옵션이 있는 드롭다운 목록을 사용합니다. 예를 들어, Append?. 추가하지 않으면 무슨 일이 일어나는지 불명확합니다(아무것도 발생하지 않거나 정보가 덮어쓰여지거나 삭제될 수 있음).

목록#

• 가능한 경우 목록에 기본값을 설정합니다. 기본값은 가장 많이 사용되는 옵션이어야 합니다.
• 목록 옵션을 알파벳 순으로 정렬합니다.
• 목록 옵션 설명을 포함할 수 있습니다. 유용한 정보를 제공하는 경우에만 설명을 추가합니다.
• All과 같은 옵션이 있는 경우 *와 같은 약어가 아닌 All 단어를 사용합니다.

Trigger node 입력#

trigger node에 트리거할 이벤트를 지정하는 파라미터가 있는 경우:

• 파라미터 이름을 Trigger on으로 지정합니다.
• 툴팁을 포함하지 않습니다.

부제목#

주요 파라미터 값을 기반으로 부제목을 설정합니다. 예를 들어:

subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',

ID#

"작업 댓글 업데이트"와 같은 특정 레코드에 대한 오퍼레이션을 수행할 때 변경하려는 레코드를 지정하는 방법이 필요합니다.

• 가능한 경우 레코드를 지정하는 두 가지 방법을 제공합니다:
  • 미리 채워진 목록에서 선택. loadOptions 파라미터를 사용하여 이 목록을 생성할 수 있습니다. 자세한 내용은 기본 파일을 참고하세요.
  • ID 입력.
• 필드 이름을 <레코드 이름> name or ID로 지정합니다. 예를 들어, Workspace Name or ID. "목록에서 이름을 선택하거나 표현식을 사용하여 ID를 지정하세요."라는 툴팁을 추가합니다. n8n의 표현식 문서에 링크합니다.
• 사용자가 필요한 것보다 더 많은 정보를 제공하는 경우를 처리할 수 있도록 node를 빌드합니다. 예를 들어:
  • 상대 경로가 필요한 경우 사용자가 절대 경로를 붙여넣는 경우를 처리합니다.
  • 사용자가 URL에서 ID를 가져와야 하는 경우 사용자가 전체 URL을 붙여넣는 경우를 처리합니다.

날짜 및 타임스탬프#

n8n은 날짜와 시간에 ISO 타임스탬프 문자열을 사용합니다. 추가하는 날짜나 타임스탬프 필드가 모든 ISO 8601 형식을 지원하는지 확인합니다.

JSON#

JSON이 예상되는 텍스트 입력의 콘텐츠를 지정하는 두 가지 방법을 지원해야 합니다:

• 텍스트 입력에 직접 JSON 입력: 결과 문자열을 JSON 오브젝트로 파싱해야 합니다.
• JSON을 반환하는 표현식 사용.

Node 아이콘#

공통 패턴 및 예외#

이 섹션은 몇 가지 엣지 케이스와 주요 표준에 대한 예외를 포함한 공통 설계 패턴 처리에 대한 지침을 제공합니다.

응답 단순화#

API는 유용하지 않은 많은 데이터를 반환할 수 있습니다. 사용자가 응답 데이터를 단순화하도록 선택할 수 있는 토글을 추가하는 것을 고려합니다:

• Name: Simplify Response
• Description: Whether to return a simplified version of the response instead of the raw data

Upsert 오퍼레이션#

항상 다음과 같은 별도의 오퍼레이션이어야 합니다:

• Name: Create or Update
• Description: Create a new record, or update the current one if it already exists (upsert)

불리언 연산자#

n8n은 GUI에서 AND 및 OR과 같은 불리언 연산자를 결합하는 것을 잘 지원하지 않습니다. 가능한 경우 모든 AND 또는 모든 OR에 대한 옵션을 제공합니다.

예를 들어, 값이 일치하는지 테스트하는 Must match 필드가 있습니다. Any 및 All을 테스트하기 위한 옵션을 별도 옵션으로 포함합니다.

소스 키 또는 바이너리 속성#

바이너리 데이터는 스프레드시트나 이미지와 같은 파일 데이터입니다. n8n에서는 데이터를 참조하기 위한 명명된 키가 필요합니다. 이 필드에 "binary data" 또는 "binary property"라는 용어를 사용하지 마세요. 대신 더 설명적인 이름을 사용합니다: Input data field name / Output data field name.