Details

    • Type: Technical Documentation
    • Status: Closed
    • Priority: Minor
    • Resolution: Completed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Headless Delivery API
    • Labels:
      None
    • Type of Documentation:
      User

      Description

      Write an overview article introducing the idea of Headless and the breadth of its features.

      Covering roughly the following content:
       

      • Intro: I want to consume a set of APIs in Liferay that were built with REST Builder – how can I do that?
        • With whatever programming language
        • Using REST/OpenAPI or GraphQL endpoints generated by REST Builder
        • REST/OpenAPI
          • Endpoints listed in Swaggerhub
          • Discoverable in a browser at [server][:port]/o/[application-name]/[version]
        • GraphQL
          • Endpoints can be discovered in a browser or via a GraphQL client
          • Found at [server][:port]/o/graphql
          • No version info necessary – only the latest version exposed, breaking changes avoided
      • Making unauthenticated requests
        • Make unauthenticated request
        • Assert it fails (with 403)
        • Open up access in Service Access Policy
        • Make unauthenticated request
        • Assert it goes through now
      • Consuming GraphQL APIs
        • Found at [server][:port]/o/graphql
        • API options available with REST APIs are generally also available in GraphQL (just with slightly different syntax)
        • [make a simple GraphQL API call]
        • Using a GraphQL client recommended for easier discovery and request editing. Discovery does not require authentication.
        • Link to how to use GraphQL clients: https://graphql.org/graphql-js/graphql-clients/
      • Authentication
        • Basic auth: Header “Authorization: Basic” followed by base64-encoded username:password
          • Should be used for development only (easily intercepted over http or by server logs, reveals complete credentials which can be used to log in, change password, and hijack your account)
        • OAuth
          • Header “Authorization: Bearer” followed by oauth token
          • Token can be intercepted (and then used to impersonate you), but can’t be used to change pw and thus hijack your account)
        • Cookie
          • Header “Cookie: JSESSIONID” followed by session ID
      • Consuming a collection API
        • Returns multiple items under “items” field
        • Gives pagination info under “lastPage”, “page”, “pageSize”, and “totalCount” fields
        • Paging can be changed with “page” and “pageSize” params in request
      • Specifying a response type
        • HTTP Headers – Accept (in request) and Content-Type (in response)
        • JSON is default
        • XML also supported OOTB
        • XML example
        • Custom APIs may allow additional response types, specified same way
      • Getting only necessary information from APIs
        • Filter
        • Sparse
        • Flatten, search, and sort also possible. See {Reference} for information on these.
      • Getting content in a specific language
        • Accept-Language header
      • Uploading a file
        • Content-Type=multipart/form-data in request
      • Reference: API parameters (several options)
      • Reference: API-relevant HTTP headers (several options)

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              richard.sezov Rich Sezov
              Reporter:
              ethan.bustad Ethan Bustad (Inactive)
              Recent user:
              Ethan Bustad (Inactive)
              Participants of an Issue:
              Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Packages

                  Version Package