traits:
client-id-required:
headers:
client_id:
type: string
client_secret:
type: string
responses:
401:
body:
application/json:
type: errors.http-401
500:
body:
application/json:
type: errors.http-500
This is part of the security library I have made. The errors are defined in the root raml so that the structure is not tied to this library and updates are related to the Application RAML and not here.
I also plan on adding the below:
securitySchemes:
basic-authentication:
type: Basic Authentication
description: Basic Authentication
describedBy:
headers:
Authorization:
required: true
type: string
description: Base64-encoded of username and password
example: |
username:password
responses:
401:
body:
application/json:
type: errors.http-401
500:
body:
application/json:
type: errors.http-500
As a security scheme it does not like the fact the errors are not defined here.
If I made it a trait it would be something like
basic-authentication:
headers:
Authorization:
required: true
type: string
description: Base64-encoded of username and password
example: |
username:password
responses:
401:
body:
application/json:
type: errors.http-401
500:
body:
application/json:
type: errors.http-500
My questions are as follows:
What is the main difference between a security scheme and a trait?
Would making the basic authentication a trait affect anything?
Just a little confused about the distinction and how it affects the functionality.
Security schemes are specialised RAML fragments design to support the definition of a range of security types (as defined here). The scheme provides a set of keys typically required for proper security configuration. A trait is a generic RAML fragment that can be used to define almost any part of an API specification design. They promote modular design and can be used to define secured endpoints when the security schema does not suffice.
In short, always use security scheme for defining secure endpoints and traits for everything else.