대부분의 노드는 API를 GUI(그래픽 사용자 인터페이스)로 표현한 것입니다. 인터페이스를 설계한다는 것은 API 엔드포인트와 매개변수를 사용자 친화적인 방식으로 표현하는 방법을 찾는 것을 의미합니다. API 전체를 그대로 노드의 폼 필드로 옮기면 좋은 사용자 경험을 만들어내지 못할 수 있습니다.

이 문서는 따라야 할 설계 가이드와 표준을 제공합니다. 이 가이드라인은 n8n이 사용하는 것과 동일합니다. 이를 통해 커뮤니티 노드와 빌트인 노드를 함께 사용하는 사용자에게 매끄럽고 일관된 사용자 경험을 제공할 수 있습니다.

설계 가이드#

모든 노드는 n8n의 노드 UI 요소를 사용하므로, 색상이나 테두리 등의 스타일 세부 사항은 신경 쓸 필요가 없습니다. 그렇지만 기본적인 설계 프로세스를 거치는 것은 여전히 유용합니다.

• 통합하려는 API의 문서를 검토하세요. 스스로에게 다음을 질문해 보세요.
  • 무엇을 생략할 수 있는가?
  • 무엇을 단순화할 수 있는가?
  • API의 어떤 부분이 헷갈리는가? 사용자가 이를 이해하도록 어떻게 도울 수 있는가?
• 와이어프레임 도구를 사용해 필드 레이아웃을 시도해 보세요. 노드에 필드가 너무 많아서 복잡해지고 있다면, 필드 표시 및 숨기기에 대한 n8n의 가이드를 참고하세요.

표준#

UI 텍스트 스타일#

UI 텍스트 용어#

• 노드가 연결하는 서비스와 동일한 용어를 사용하세요. 예를 들어 Notion 노드는 Notion 문단이 아니라 Notion 블록이라고 표현해야 합니다. Notion이 이러한 요소를 블록이라고 부르기 때문입니다. 이 규칙에는 예외가 있으며, 대개는 기술 용어를 피하기 위한 것입니다(예: upsert 작업의 이름 및 설명에 대한 가이드를 참고하세요).
• 어떤 서비스는 API와 GUI에서 같은 대상을 다른 용어로 부르기도 합니다. 대부분의 사용자에게 익숙한 것은 GUI 용어이므로, 노드에서는 GUI 언어를 사용하세요. 일부 사용자가 해당 서비스의 API 문서를 참고해야 할 수도 있다고 생각되면, 이 정보를 힌트에 포함하는 것을 고려하세요.
• 더 간단한 대안이 있는데도 전문 용어를 사용하지 마세요.
• 이름을 지을 때는 일관성을 유지하세요. 예를 들어 directory와 folder 중 하나를 선택했다면 계속 그것만 사용하세요.

노드 명명 규칙#

필드 표시 및 숨기기#

필드는 다음 중 하나가 될 수 있습니다.

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

복잡성을 점진적으로 드러내세요. 즉, 앞선 필드에 값이 입력되기 전까지는 그 값에 의존하는 필드를 숨깁니다. 예를 들어 Filter by date 토글과 Date to filter by 날짜 선택기가 있다면, 사용자가 Filter by date를 활성화하기 전에는 Date to filter by를 표시하지 마세요.

필드 유형별 규칙#

자격 증명#

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

리소스와 오퍼레이션#

일반적으로 API는 데이터에 어떤 작업을 수행하는 것과 관련이 있습니다. 예를 들어 "모든 태스크 가져오기(get all tasks)"의 경우, "태스크"가 리소스이고 "모두 가져오기"가 오퍼레이션입니다.

노드가 이러한 리소스와 오퍼레이션 패턴을 가진다면, 첫 번째 필드는 Resource, 두 번째 필드는 Operation이어야 합니다.

필수 필드#

다음 기준으로 필드 순서를 정하세요.

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

선택적 필드#

• 필드를 알파벳 순으로 정렬하세요. 비슷한 항목을 그룹화하려면 이름을 다시 지어도 됩니다. 예를 들어 Email과 Secondary Email을 **Email (primary)**과 **Email (secondary)**로 이름을 바꿀 수 있습니다.
• 선택적 필드에 값이 설정되지 않았을 때 노드가 사용하는 기본값이 있다면, 그 값을 필드에 미리 로드하세요. 필드 설명에 이를 설명하세요. 예를 들어 Defaults to false처럼요.
• 연결된 필드: 선택적 필드 하나가 다른 필드에 의존한다면, 두 필드를 함께 묶으세요. 두 필드는 선택 시 둘 다 표시되는 하나의 옵션 아래에 있어야 합니다.
• 선택적 필드가 많다면, 주제별로 그룹화하는 것을 고려하세요.

도움말#

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

• 정보 박스: 필드 사이에 나타나는 노란색 박스입니다. 자세한 내용은 UI 요소 | Notice를 참고하세요.
  • 필수적인 정보에만 정보 박스를 사용하세요. 과도하게 사용하지 마세요. 드물게 사용해야 더 눈에 띄어 사용자의 주의를 끌 수 있습니다.
• 매개변수 힌트: 사용자 입력 필드 아래에 표시되는 텍스트 줄입니다. 사용자가 알아야 할 내용이 있지만 정보 박스를 사용하기엔 과할 때 사용하세요.
• 노드 힌트: 입력 패널, 출력 패널, 또는 노드 세부 정보 뷰에서 도움말을 제공합니다. 자세한 내용은 UI 요소 | Hints를 참고하세요.
• 툴팁: 사용자가 툴팁 아이콘 위에 마우스를 올렸을 때 나타나는 콜아웃입니다. 사용자가 필요로 할 수 있는 추가 정보에 툴팁을 사용하세요.
  • 모든 필드에 툴팁을 제공할 필요는 없습니다. 유용한 정보가 담긴 경우에만 추가하세요.
  • 툴팁을 작성할 때는 사용자가 필요로 하는 것이 무엇인지 생각하세요. API 매개변수 설명을 그대로 복사-붙여넣기 하지 마세요. 설명이 이해되지 않거나 오류가 있다면 개선하세요.
• 플레이스홀더 텍스트: n8n은 사용자가 값을 입력하지 않은 필드에 플레이스홀더 텍스트를 표시할 수 있습니다. 이는 사용자가 해당 필드에 무엇을 입력해야 하는지 알 수 있도록 도와줍니다.

정보 박스, 힌트, 툴팁에는 더 많은 정보로 연결되는 링크를 포함할 수 있습니다.

오류#

어떤 필드가 필수인지 명확히 표시하세요.

가능하다면 필드에 유효성 검사 규칙을 추가하세요. 예를 들어 필드가 이메일을 요구한다면 유효한 이메일 패턴인지 확인하세요.

오류를 표시할 때는 빨간색 오류 제목에는 주요 오류 메시지만 표시되도록 하세요. 더 자세한 정보는 Details에 넣어야 합니다.

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

토글#

• 이진 상태에 대한 툴팁은 **Whether to . . .**와 같은 형태로 시작해야 합니다.
• 토글 대신 목록이 필요할 수도 있습니다.
  • false 상태에서 어떤 일이 일어나는지 명확할 때는 토글을 사용하세요. 예를 들어 **Simplify Output?**의 경우, 대안(출력을 단순화하지 않음)이 명확합니다.
  • 더 명확한 설명이 필요할 때는 이름이 지정된 옵션이 있는 드롭다운 목록을 사용하세요. 예를 들어 **Append?**의 경우, append하지 않으면 어떤 일이 일어나는지 불분명합니다(아무 일도 일어나지 않거나, 정보가 덮어써지거나, 폐기될 수도 있습니다).

목록#

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

트리거 노드 입력#

트리거 노드에 어떤 이벤트에서 트리거할지 지정하는 매개변수가 있는 경우:

• 매개변수 이름을 Trigger on으로 지정하세요.
• 툴팁을 포함하지 마세요.

서브타이틀#

주요 매개변수의 값을 기준으로 서브타이틀을 설정하세요. 예를 들면 다음과 같습니다.

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

ID#

"태스크 코멘트 업데이트"처럼 특정 레코드에 대해 작업을 수행할 때는, 변경할 레코드를 지정할 방법이 필요합니다.

• 가능하면 레코드를 지정하는 두 가지 방법을 제공하세요.
  • 미리 채워진 목록에서 선택하는 방법. loadOptions 매개변수를 사용하여 이 목록을 생성할 수 있습니다. 자세한 내용은 Base files를 참고하세요.
  • ID를 직접 입력하는 방법.
• 필드 이름을 <레코드 이름> name or ID 형식으로 지정하세요. 예를 들어 Workspace Name or ID처럼요. "Choose a name from the list, or specify an ID using an expression."라는 툴팁을 추가하세요. n8n의 Expressions 문서로 링크를 거세요.
• 사용자가 필요 이상의 정보를 입력하는 경우도 처리할 수 있도록 노드를 만드세요. 예를 들어:
  • 상대 경로가 필요하다면, 사용자가 절대 경로를 붙여넣는 경우도 처리하세요.
  • 사용자가 URL에서 ID를 가져와야 한다면, 사용자가 URL 전체를 붙여넣는 경우도 처리하세요.

날짜와 타임스탬프#

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

JSON#

JSON을 기대하는 텍스트 입력의 콘텐츠를 지정하는 두 가지 방법을 지원해야 합니다.

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

노드 아이콘#

공통 패턴과 예외#

이 섹션에서는 몇 가지 엣지 케이스와 주요 표준의 예외를 포함하여, 공통 설계 패턴을 처리하는 방법에 대한 가이드를 제공합니다.

응답 단순화#

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

• 이름: Simplify Response
• 설명: Whether to return a simplified version of the response instead of the raw data

Upsert 작업#

이는 항상 별도의 오퍼레이션이어야 하며, 다음과 같이 지정합니다.

• 이름: Create or Update
• 설명: 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을 사용하세요.