• Technical Documentation
    • Status: Closed
    • Minor
    • Resolution: Completed
    • None
    • None
    • Headless Delivery API
    • None
    • User


      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:
      • 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)


        Issue Links



              richard.sezov Rich Sezov
              ethan.bustad Ethan Bustad (Inactive)
              Ethan Bustad Ethan Bustad (Inactive)
              0 Vote for this issue
              0 Start watching this issue




                  Version Package