Skip to main content

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.

1 answer
  1. Jan 24, 2021, 6:18 PM

    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.