OpenRPC

What is an OpenRPC Specification?

The OpenRPC Specification is a framework used by developers to document JSON-RPC APIs. The specification is written in JSON or YAML and contains all of your methods, parameters, schemas, and server configurations. Fern is compatible with OpenRPC specification v1.3.2 and v1.2.6.

Below is an example of an OpenRPC file:

openrpc.yml
1openrpc: 1.3.2
2info:
3  title: Calculator API
4  version: 1.0.0
5  description: |
6    A simple calculator API that performs basic arithmetic operations
7    using JSON-RPC 2.0 protocol.
8servers:
9  - name: production
10    url: https://api.calculator.com/rpc
11    description: Production JSON-RPC server
12  - name: development  
13    url: http://localhost:8080/rpc
14    description: Development server
15methods:
16  - name: add
17    summary: Add two numbers
18    description: Performs addition of two numeric values
19    params:
20      - name: a
21        schema:
22          type: number
23        required: true
24        description: First number to add
25      - name: b
26        schema:
27          type: number
28        required: true
29        description: Second number to add
30    result:
31      name: sum
32      schema:
33        type: number
34      description: The sum of the two numbers
35    examples:
36      - name: AddExample
37        description: Example of adding two numbers
38        params:
39          a: 5
40          b: 3
41        result: 8
42  - name: divide
43    summary: Divide two numbers
44    description: Performs division of two numeric values
45    params:
46      - name: dividend
47        schema:
48          type: number
49        required: true
50        description: Number to be divided
51      - name: divisor
52        schema:
53          type: number
54        required: true
55        description: Number to divide by
56    result:
57      name: quotient
58      schema:
59        type: number
60      description: The result of the division
61    errors:
62      - code: -32602
63        message: Division by zero
64        data:
65          type: object
66          properties:
67            error:
68              type: string
69              const: "Cannot divide by zero"
70    examples:
71      - name: DivideExample
72        description: Example of dividing two numbers
73        params:
74          dividend: 10
75          divisor: 2
76        result: 5
77  - name: notify_calculation
78    summary: Notify about calculation
79    description: Send a notification about a completed calculation (no response expected)
80    params:
81      - name: operation
82        schema:
83          type: string
84          enum: [add, subtract, multiply, divide]
85        required: true
86      - name: result
87        schema:
88          type: number
89        required: true
90      - name: timestamp
91        schema:
92          type: string
93          format: date-time
94        required: true
95components:
96  schemas:
97    CalculationRequest:
98      type: object
99      properties:
100        operation:
101          type: string
102          enum: [add, subtract, multiply, divide]
103        operands:
104          type: array
105          items:
106            type: number
107          minItems: 2
108          maxItems: 2
109        precision:
110          type: integer
111          minimum: 0
112          maximum: 10
113          default: 2
114      required:
115        - operation
116        - operands
117    CalculationResult:
118      type: object
119      properties:
120        result:
121          type: number
122        operation:
123          type: string
124        timestamp:
125          type: string
126          format: date-time
127      required:
128        - result
129        - operation
130        - timestamp

Set up your fern folder

Considering options to generate an OpenRPC spec? Get live support here
1

Create your fern directory

Create a fern/ folder in your project root.

fern/
2

Add your OpenRPC specification

Add your OpenRPC spec to the fern directory. You can place it in a subfolder called openrpc or directly in the fern directory.

fern/
  └─ openrpc/
    └─ openrpc.yml
3

Create a fern.config.json file

Add a fern.config.json file in your fern directory that lists your organization and the current version of the Fern CLI:

fern.config.json
1{
2    "organization": "your-organization",
3    "version": "0.77.5"
4}
fern/
  ├─ fern.config.json
  └─ openrpc/
    └─ openrpc.yml
4

Create a generators.yml file

Create a generators.yml file in your fern directory and add a reference to your OpenRPC spec:

generators.yml
1# Your API definition
2api: 
3  specs: 
4    - openrpc: ./openrpc/openrpc.yml
5
6groups:
7  external:
8    generators:
9      # Your generator configurations here

Your final directory structure:

fern/
  ├─ fern.config.json
  ├─ generators.yml
  └─ openrpc/
    └─ openrpc.yml