upstream-rocketchat/packages/rest-typings/README.md

#  @rocket.chat/rest-typings

Package containing all Rocket.Chat rest endpoint definitions


## Contributing

Contributions are always welcome!
However we have some recommendations.
- Check if your implementation matches your definitions, a bad definition is worse than none.
- Use the generic types we created for paging.
- Create functions that assert properties (very useful for the backend)
- Do tests to ensure that your assertions are correct.
- Avoid incomplete and unknow typings

### Good examples of what not to do:

#### If you have an endpoint that accepts name or id, both are not optional, one of them is required

```typescript
    
    type EndPointTestGetParams = { name?: string; id?: string; } // WRONG!

    type EndPointTestGetParams = { name: string; } | { id: string; } // Better :)
````

#### If you have an endpoint that accepts name or id, both are not optional, one of them is required

```typescript
    export const isEndPointTestGetParams = (props: any) is EndPointTestGetParams => 'name' in prop || 'id' in prop; // WRONG!

    // .... Better
    
    
    import Ajv from 'ajv';

    const ajv = new Ajv();
    const endPointTestGetParams = {
        oneOf: [
            {
                type: 'object',
                properties: {
                    name: {
                        type: 'string',
                    },
                },
                required: ['name'],
                additionalProperties: false,
            },
            {
                type: 'object',
                properties: {
                    id: {
                        type: 'string',
                    },
                },
                required: ['id'],
                additionalProperties: false,
            },
        ],
    };

    export const isEndPointTestGetParams = ajv.compile<EndPointTestGetParams>(endPointTestGetParams);
```
## Optimizations

we use interfaces to register endpoints, so if you use a custom version, or miss an endpoint, you don't necessarily need to recompile the code, you can do it in your own code

```typescript
    declare module '@rocket.chat/rest-typings' {
        interface Endpoints {
            'custom/endpoint': {
                GET: (params: PaginatedRequest<{ query: string }>) => PaginatedResult<{
                    some: string[];
                }>;
            };
        }
    }
```

## License

MIT